Visualization Patterns

Skill: Visualization Patterns

Purpose

Ensure every chart Claude Code produces follows high-quality design standards with named themes, consistent styling, and clear data communication.

When to Use

Apply this skill whenever generating a chart, graph, or data visualization.

When someone asks for a pie chart

Do not make the pie. Make the sorted bar (or a single stacked bar for parts of a whole), say in one sentence why (angles and areas are hard to compare; a bar shows the same shares with direct labels), and offer the pie only if they insist after seeing the bar. Producing both "to be safe" is not the standard; the bar is the deliverable.

Default Theme: Minimal

When no theme or palette is set, use the default styling without asking; offer palette options only when the user asks about themes or colors.

The minimal theme is clean, professional, and suitable for most business contexts:

• Warm off-white background (#F7F6F2) for reduced eye strain
• Focus blue accent (#0072B2, an Okabe-Ito color) for the one element the takeaway argues
• Helvetica font family
• Left-aligned titles, minimal gridlines

The swd_style() function automatically loads the minimal theme. Other available themes: nyt, economist, corporate (see Theme Definitions section).

Instructions

STEP 1: Import the SWD helpers

Start every chart with the helpers in helpers/viz/chart_helpers.py; they set the R3 background, gray-plus-accent palette, direct labels and spine cleanup that the checkpoints verify.

from helpers.viz.chart_helpers import (
    swd_style,        # Apply SWD matplotlib theme
    highlight_bar,    # Bar chart with one bar highlighted
    highlight_line,   # Line chart with one series highlighted
    action_title,     # Action title + subtitle
    save_chart        # Save with correct DPI and tight layout
)

# Apply SWD style FIRST (loads .mplstyle, returns color palette)
colors = swd_style()

If helpers/viz/chart_helpers.py doesn't exist: Inform the user that chart helpers are missing and you'll need to implement SWD principles manually. Then proceed with manual matplotlib following the SWD principles below.

STEP 2: Choose Your Helper Function

Use the pre-built helpers instead of manual matplotlib code:

Key points:

• Helpers take a matplotlib ax object + arrays of data (not DataFrames)
• Always create the figure first: fig, ax = plt.subplots(figsize=(10, 6))
• Helpers automatically apply: gray + accent color, direct labels, SWD styling
• The highlight parameter specifies which category/series to emphasize

For funnel charts, heatmaps, or custom visualizations: Use manual matplotlib but apply swd_style() first and follow the SWD principles below.

STEP 3: Save Chart to Correct Location

# Final deliverable charts
save_chart(fig, "outputs/conversion_by_device.png")

# Exploratory/intermediate charts
save_chart(fig, "working/exploration_chart.png")

Naming convention: {metric}_{dimension}_{chart_type}.png (e.g., revenue_trends_line.png)

Pre-flight: Load Learnings (Optional)

Check .knowledge/learnings/index.md for relevant entries:

• Read the file. If it doesn't exist or is empty, skip silently.
• Scan for entries under "Chart Style" and "General" headings.
• If entries exist, incorporate them as constraints (e.g., preferred chart types, color overrides).
• Never block execution if learnings are unavailable.

Core Principle: Storytelling with Data (SWD)

Every chart follows the SWD methodology by Cole Nussbaumer Knaflic:

Gray everything first. Color is reserved for the one data point that tells the story.

• Mostly gray. One focus accent, blue (#0072B2), for the element the takeaway argues; a second accent, orange (#D55E00), only for a genuine two-focal or good-vs-bad case. Both are Okabe-Ito colors, so the pair is colorblind-safe (blue vs orange, never red vs green). Everything else is gray. Use up to 5 Okabe-Ito categoricals ONLY when categories are truly independent; more than that is a signal to rethink the chart, never to add hues. (Amber #D97706 is the deck/thumbnail brand color; it is not a chart focus color.)
• Titles state the takeaway, not a description. "iOS drove the June ticket spike" not "Tickets by Platform."
• Every visual element must earn its place — if it doesn't help the reader understand the story, remove it.
• Prefer text over charts for single numbers. Prefer horizontal bars over pie charts. Prefer direct labels over legends.

Why use the helpers: They enforce these principles automatically. Manual matplotlib code often forgets to remove borders, uses rainbow colors, or includes legends. The helpers prevent these mistakes.

Declutter Checklist

Before finalizing any chart, verify each item:

• Chart border / box — removed entirely
• Top and right spines — removed (keep only bottom and left)
• Heavy gridlines — removed or very light gray (#E5E7EB), y-axis only
• Data markers — removed from line charts (the line is the data)
• Legend — replaced with direct labels on the data
• Rotated axis text — if labels need rotation, switch to horizontal bars
• Trailing zeros — use $45 not $45.00; use 12% not 12.0%
• 3D effects — never
• Background color — always warm off-white (#F7F6F2)
• Redundant axis labels — if the title says "Revenue ($M)", the y-axis doesn't need "Revenue in Millions of Dollars"
• Excessive tick marks — reduce to 4-6 ticks maximum
• Decimal precision — match the precision to the decision (12% not 12.347%)

Chart Sequencing (Multi-Chart Analyses)

When producing multiple charts for a deep dive or root cause investigation, follow Context → Tension → Resolution:

• Each chart builds on the previous one
• Never show a chart that makes the audience ask "so what?"
• The number of charts is determined by the storyboard. Each narrative beat that requires a visualization becomes a chart.
• The final chart should make the recommended action obvious

Chart Helper Functions Reference

All chart helpers live in helpers/viz/chart_helpers.py. The style file is helpers/viz/analytics_chart_style.mplstyle. The full style guide with before/after examples is in helpers/viz/chart_style_guide.md.

Theme Definitions

Theme: nyt (New York Times)

NYT_THEME = {
    "colors": {
        "primary": "#000000",
        "secondary": "#666666",
        "accent": "#D03A2B",
        "palette": ["#D03A2B", "#1A6B54", "#3D6CA3", "#E8912D", "#8B5E3C", "#6B4C9A"],
        "background": "#FFFFFF",
        "grid": "#E5E5E5",
    },
    "fonts": {
        "title": {"family": "Georgia", "size": 18, "weight": "bold"},
        "subtitle": {"family": "Arial", "size": 12, "weight": "normal", "color": "#666666"},
        "axis_label": {"family": "Arial", "size": 10},
        "annotation": {"family": "Arial", "size": 9, "style": "italic"},
    },
    "grid": {"show": True, "axis": "y", "style": "--", "alpha": 0.3},
    "annotations": {"style": "minimal", "callout_arrows": True},
    "title": {"position": "left-aligned", "include_subtitle": True},
}

Theme: economist (The Economist)

ECONOMIST_THEME = {
    "colors": {
        "primary": "#1F2E3C",
        "secondary": "#7C8A96",
        "accent": "#E3120B",
        "palette": ["#E3120B", "#1F6ED4", "#36B37E", "#F5A623", "#6554C0", "#00B8D9"],
        "background": "#D7E4E8",
        "grid": "#FFFFFF",
    },
    "fonts": {
        "title": {"family": "Helvetica", "size": 16, "weight": "bold"},
        "subtitle": {"family": "Helvetica", "size": 11, "weight": "normal"},
        "axis_label": {"family": "Helvetica", "size": 9},
        "annotation": {"family": "Helvetica", "size": 8},
    },
    "grid": {"show": True, "axis": "y", "style": "-", "alpha": 0.5, "color": "#FFFFFF"},
    "annotations": {"style": "inline", "red_highlight": True},
    "title": {"position": "left-aligned", "red_bar_top": True},
}

Theme: minimal

MINIMAL_THEME = {
    "colors": {
        "primary": "#1F2937",
        "secondary": "#4B5563",
        "accent": "#0072B2",
        "palette": ["#0072B2", "#D55E00", "#009E73", "#CC79A7", "#404040"],
        "background": "#F7F6F2",
        "grid": "#F0F0F0",
    },
    "fonts": {
        "title": {"family": "Helvetica", "size": 14, "weight": "bold"},
        "subtitle": {"family": "Helvetica", "size": 10, "weight": "normal", "color": "#666666"},
        "axis_label": {"family": "Helvetica", "size": 9},
        "annotation": {"family": "Helvetica", "size": 8},
    },
    "grid": {"show": True, "axis": "y", "style": "-", "alpha": 0.15},
    "annotations": {"style": "minimal", "direct_labels": True},
    "title": {"position": "left-aligned", "include_subtitle": True},
}

Theme: corporate

CORPORATE_THEME = {
    "colors": {
        "primary": "#1B2A4A",
        "secondary": "#5A6B7F",
        "accent": "#0066CC",
        "palette": ["#0066CC", "#00A651", "#FF6600", "#CC0000", "#9933CC", "#00CCCC"],
        "background": "#FFFFFF",
        "grid": "#E8E8E8",
    },
    "fonts": {
        "title": {"family": "Arial", "size": 16, "weight": "bold"},
        "subtitle": {"family": "Arial", "size": 11, "weight": "normal"},
        "axis_label": {"family": "Arial", "size": 10},
        "annotation": {"family": "Arial", "size": 9},
    },
    "grid": {"show": True, "axis": "both", "style": "-", "alpha": 0.2},
    "annotations": {"style": "callout", "box_highlight": True},
    "title": {"position": "center", "include_subtitle": True},
}

Applying a Theme (matplotlib)

import matplotlib.pyplot as plt
import matplotlib.ticker as mticker

def apply_theme(fig, ax, theme):
    """Apply a named theme to a matplotlib figure."""
    fig.patch.set_facecolor(theme["colors"]["background"])
    ax.set_facecolor(theme["colors"]["background"])

    # Title styling
    ax.set_title(
        ax.get_title(),
        fontfamily=theme["fonts"]["title"]["family"],
        fontsize=theme["fonts"]["title"]["size"],
        fontweight=theme["fonts"]["title"]["weight"],
        loc="left" if theme["title"]["position"] == "left-aligned" else "center",
        pad=15,
    )

    # Grid
    if theme["grid"]["show"]:
        ax.grid(
            axis=theme["grid"]["axis"],
            linestyle=theme["grid"]["style"],
            alpha=theme["grid"]["alpha"],
            color=theme["colors"].get("grid", "#E0E0E0"),
        )
        ax.set_axisbelow(True)

    # Clean spines
    ax.spines["top"].set_visible(False)
    ax.spines["right"].set_visible(False)
    ax.spines["left"].set_alpha(0.3)
    ax.spines["bottom"].set_alpha(0.3)

    # Axis labels
    ax.xaxis.label.set_fontfamily(theme["fonts"]["axis_label"]["family"])
    ax.xaxis.label.set_fontsize(theme["fonts"]["axis_label"]["size"])
    ax.yaxis.label.set_fontfamily(theme["fonts"]["axis_label"]["family"])
    ax.yaxis.label.set_fontsize(theme["fonts"]["axis_label"]["size"])

    plt.tight_layout()