data-story

<essential_principles>

The Six Lessons of Storytelling with Data

These principles transform data from noise into narrative. Apply them in order.

1. Understand the Context

Before touching any tool, answer three questions:

WHO is your audience?

• •What do they know? What do they need to know?
• •What biases or preconceptions do they have?
• •What will make them care?

WHAT do you want them to do?

• •Be specific: "approve the budget" not "understand the situation"
• •If you can't articulate the action, you're not ready to visualize

HOW will you communicate?

• •Live presentation? Written report? Dashboard?
• •This determines level of detail and annotation needed

<context_checklist> Before creating any visualization:

• • I can state my audience in one sentence
• • I can state the desired action in one sentence
• • I know the communication mechanism
• • I have identified the "So What?" - why should they care? </context_checklist>

2. Choose an Effective Visual

The right chart for the job:

Default choices:

• •When in doubt: simple bar chart or line chart
• •Tables: Use when audience needs exact values
• •Text: Use when you have 1-2 numbers to communicate

<chart_selection_rules> ALWAYS avoid:

• •Pie charts (except 2-3 slices max)
• •3D effects (distorts perception)
• •Dual y-axes (confuses correlation with causation)
• •Donut charts (harder to compare than pie)
• •Radar/spider charts (difficult to read)

PREFER:

• •Horizontal bars over vertical (labels read naturally)
• •Line charts for time (even with few points)
• •Direct labels over legends </chart_selection_rules>

3. Eliminate Clutter

Clutter is your enemy. Every element should earn its place.

Remove ruthlessly:

• •Chart borders and backgrounds
• •Gridlines (or lighten to near-invisible)
• •Data markers on lines (unless highlighting specific points)
• •Legends (use direct labels instead)
• •Axis lines (data speaks for itself)
• •Bold/italic formatting (unless strategic)

The Declutter Checklist:

For each element ask: "Would removing this change the meaning?"
If NO → Remove it
If YES → Keep it (but consider if it can be lighter/smaller)

<clutter_identification> Visual clutter includes:

• •Borders, boxes, shading that don't encode data
• •Heavy gridlines
• •Unnecessary axis labels or tick marks
• •Legends (when direct labels would work)
• •Data markers on every point
• •Gradient fills
• •3D effects
• •Rotated text
• •Unnecessary precision (3.14159 → 3.1) </clutter_identification>

4. Focus Attention

Use preattentive attributes strategically.

Preattentive attributes (processed in <500ms):

• •Color - Most powerful. Use sparingly for emphasis.
• •Size - Larger = more important
• •Position - Top-left gets seen first (in Western reading)
• •Enclosure - Boxes draw attention
• •Bold - For headlines and key numbers only

<attention_strategy> The hierarchy of emphasis:

1. •ONE thing should be boldest/brightest (your main point)
2. •Supporting elements in medium gray
3. •Everything else in light gray or removed

COLOR RULES:

• •Gray is your friend (use for de-emphasis)
• •ONE accent color for emphasis
• •Never use red/green alone (colorblindness)
• •Brand colors are fine, but don't let them drive design </attention_strategy>

5. Think Like a Designer

Affordances: Make it obvious how to read your visual

• •Clear title that states the insight (not just the topic)
• •Axis labels that don't require rotation
• •Annotations that explain, not just label

Accessibility:

• •Sufficient contrast (4.5:1 minimum)
• •Don't rely on color alone
• •Alt text for screen readers

Alignment:

• •Left-align text (easier to scan)
• •Align data to make comparisons easy
• •Use consistent spacing

<design_checklist>

• • Title states the insight ("Sales grew 15%" not "Sales Data")
• • No rotated text
• • Direct labels instead of legend where possible
• • Consistent color meaning across visuals
• • White space used intentionally
• • Mobile-friendly if needed </design_checklist>

6. Tell a Story

Structure your narrative:

Beginning: Set up the context

• •What's the current situation?
• •Why does this matter now?

Middle: Build the tension

• •What's the problem or opportunity?
• •What are the stakes?

End: Resolve with action

• •What should the audience do?
• •What happens if they don't?

<story_framework> The "So What?" test: After every insight, ask "So what?" until you reach the action.

Example:

• •"Sales are down 10%" → So what?
• •"We're missing Q3 targets" → So what?
• •"We need to approve the new marketing campaign by Friday" ← THIS is your story's conclusion </story_framework> </essential_principles>

1. •Review a visualization (get improvement suggestions)
2. •Choose a chart type for my data
3. •Declutter an existing visualization
4. •Focus attention on key insights
5. •Structure a data story/presentation

Share your visualization, data, or context and I'll apply the SWD framework. </intake>

<review_process>

SWD Review Framework

When reviewing any visualization, evaluate in this order:

1. Context Check

• •Is the audience clear?
• •Is the action explicit?
• •Is the "So What?" obvious?

2. Chart Type Audit

• •Is this the right chart for the data relationship?
• •Would a simpler chart work?
• •Are there SWD-forbidden elements (pie charts, 3D, dual axes)?

3. Clutter Scan

• •Borders, gridlines, backgrounds → Remove or lighten?
• •Legend → Can it be direct labels?
• •Axis elements → Minimum necessary?
• •Precision → Appropriate decimal places?

4. Attention Assessment

• •What's the ONE thing that should stand out?
• •Is color used sparingly and strategically?
• •Is gray used for de-emphasis?

5. Story Structure

• •Does the title state the insight?
• •Is there clear narrative arc?
• •Does it end with a call to action?

<quick_fixes>

Common Problems → Quick Fixes

<code_patterns>

Implementation Patterns

D3.js - SWD-Compliant Defaults

// Minimal, clean styling
const swd = {
  colors: {
    emphasis: '#2563eb',    // Blue for focus
    neutral: '#6b7280',     // Gray for context
    background: '#ffffff',
    light: '#e5e7eb'        // Very light gray for subtle gridlines
  },
  axis: {
    tickSize: 0,            // No tick marks
    strokeWidth: 0          // No axis lines
  },
  grid: {
    stroke: '#f3f4f6',      // Nearly invisible
    strokeDasharray: '2,2'  // Dotted if needed
  }
};

// Direct labels over legends
bars.append('text')
  .attr('x', d => x(d.value) + 5)
  .attr('y', d => y(d.category) + y.bandwidth() / 2)
  .attr('dy', '0.35em')
  .text(d => d.value);

Tailwind CSS - SWD Palette

/* De-emphasis (most elements) */
.swd-muted { @apply text-gray-400; }

/* Normal context */
.swd-neutral { @apply text-gray-600; }

/* Emphasis (ONE thing) */
.swd-emphasis { @apply text-blue-600 font-semibold; }

/* Remove chart chrome */
.swd-clean-chart {
  @apply border-0 bg-transparent;
}

</code_patterns>

<success_criteria> A visualization passes the SWD test when:

• • A stranger can identify the main point in 5 seconds
• • The title states an insight, not a topic
• • Color is used for ONE purpose only
• • No legends (direct labels used)
• • No 3D, pie charts (>3 slices), or dual axes
• • Gridlines are invisible or nearly so
• • The audience knows what to do next </success_criteria>