Data Visualization

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

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.

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

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