data-visualization

name	data-visualization
description	Use when building dashboards, charts, or data displays, when defining chart type selection rules, when standardizing data color encoding, or when charts look inconsistent across the product.

Data Visualization

Overview

Pin down chart-type selection rules, data color encoding, axis conventions, responsive behavior, empty states, and load animations before charts proliferate. Output is .forge/data-visualization.md. Reads design-system (color palette, typography) and component-library (chart components). Referenced by every dashboard, report, and analytics surface.

When to Use

• A dashboard or analytics surface is being built and no chart conventions exist
• Charts across the product use 8 different color palettes and 3 different tooltip styles
• A new chart type is being added and the team needs a rule for when to use it
• Data colors don't track design tokens (raw #3B82F6 inside chart code)
• A report needs to work on mobile and the existing charts don't respond

When NOT to Use

• A single one-off chart on a marketing page — use the design system colors and move on
• A product with no data surfaces (auth, settings, content)
• A backend-only service

Common Rationalizations

Thought	Reality
"Just use whatever chart looks good"	Mismatched chart types across a dashboard look like three different products stitched together.
"We'll standardize later"	By then you have 8 charts with 8 different palettes and 3 tooltip styles.
"Pie charts are fine"	Humans can't accurately compare angles. Donuts with center metrics beat pies; horizontal bars beat both for comparison.
"We don't need empty states for charts"	A blank chart area makes users think the product is broken.
"Hover tooltips work everywhere"	Hover doesn't exist on touch. Every tooltip needs a tap path.

Red Flags

• Pie chart used for comparison (use horizontal bar)
• Color as the only differentiator (no patterns/labels/icons for accessibility)
• Y-axis not starting at 0 (misleading without a "delta" framing)
• Inconsistent date formats across charts (MMM DD here, MM/DD/YY there)
• Chart with no empty state — just a blank rectangle
• Tooltip that only works on hover (unusable on touch)
• More than 5 distinct colors in one chart

Core Process

Step 1: Read upstream artifacts

Read .forge/design-system.md for color palette + typography. Read .forge/component-library.md for the chart components catalog. If charts aren't yet catalogued, add them in component-library first.

Step 2: Chart type selection — a decision tree, not a vibe

Document the rules. Charts are picked by data shape, not aesthetics.

Data shape	Chart type
Trend over time	Line (or area if cumulative)
Part of whole	Donut with center metric (never pie)
Comparison across categories	Horizontal bar (labels remain readable)
Distribution	Histogram or box plot
Correlation	Scatter plot
Ranking	Sorted horizontal bar
Performance score	Gauge or radial progress
Multi-axis comparison	Radar (sparingly — humans struggle past 5 axes)
Geographic	Map (only when geography drives the insight)
Time-of-day / frequency matrix	Heatmap

Step 3: Data color encoding

Semantic, not decorative. All colors come from design-system tokens.

• Performance / positive → green gradient (success token family)
• Risk / negative → red gradient (error / danger token family)
• Neutral / informational → blue gradient (primary token family)
• Comparison series → max 5 distinct colors, ordered by semantic weight (most prominent series gets accent)
• Sequential data → single-hue gradient, dark to light
• Accessibility floor: never color-only. Add patterns (dashes, dots), labels, or icons so the encoding survives grayscale and color blindness.

Step 4: Axis + label conventions

• Y-axis starts at 0 (exception: change/delta charts, which must be labeled as such)
• Labels inside the chart when space allows, outside when crowded
• Units always shown: %, $, count, ms
• Date format consistent product-wide (e.g., MMM DD for English locales)
• Truncate long category labels with ellipsis + tooltip; never wrap

Step 5: Responsive chart behavior

Breakpoint	Behavior
Desktop	Full chart with legend beside; tooltip on hover or tap
Tablet	Chart fills width; legend below
Mobile	Simplified chart (fewer data points or aggregated bins); legend as dropdown or hidden; tap-only tooltip
Touch	Tap toggles tooltip; tooltip dismisses on outside tap

Never depend on hover. Every interaction has a tap path.

Step 6: Empty states for charts

A chart with no data is not a blank area. Show:

• Headline: "No data yet" (per brand-identity voice)
• Context: "Calls from this week will appear here" or "Import data to see trends"
• Optional CTA: link to the source of data or to documentation

Step 7: Animation on data load

• Staggered reveal per references/motion-system.md chart section — bars grow, lines draw, numbers count up
• Duration: emphasis-tier (400–500ms) on first load; standard (200–300ms) on update
• Respect prefers-reduced-motion — collapse to instant appearance, opacity fade only

Step 8: Domain-specific patterns

If the product is data-heavy, document recurring chart patterns by domain:

• Score distribution — histogram with performance bands (red / yellow / green zones)
• Trend lines — 7-day moving average overlaid on daily points
• Team comparison — grouped bar, sorted by aggregate
• Volume by time-of-day — area chart + heatmap; aligns to the analytics narrative

If not data-heavy, skip — don't invent patterns to fill the section.

Step 9: Write .forge/data-visualization.md

Section order: upstream-read confirmation, chart selection rules, color encoding, axis + labels, responsive behavior, empty states, animation, domain-specific patterns. Prepend a forge:meta header (generated_by: data-visualization, generated_at: <ISO 8601 UTC with Z>, depends_on: [.forge/design-system.md, .forge/component-library.md] — paths only, never hashes, generated_from: {.forge/design-system.md: <hash>, .forge/component-library.md: <hash>} — each upstream's content_hash AT generation time, content_hash: <sha256 first 8 of THIS file's body>).

Verification

• Chart selection has a rule for every chart type the product uses (no ad-hoc choices)
• Color encoding is consistent across the product and accessible (not color-only)
• Every chart type has an empty state with context, not a blank area
• No chart depends on hover — every tooltip has a tap path
• Animation respects prefers-reduced-motion
• Y-axis policy documented (starts at 0 except for delta/change charts, which must be labeled)
• No raw hex in chart code — every color is a design-system token
• Domain-specific patterns documented if the product is data-heavy (or skipped with reason)
• .forge/data-visualization.md written with forge:meta header