Data Visualization

Senior reference for charts in product UI. Assumes the reader can read a chart; the goal is to surface the encoding decisions, axis-honesty rules, and accessibility patterns that separate a credible chart from a pretty one.

Constitution (verbatim — applies to every artifact)

1. Max 300 lines per file. If a generated component would exceed, split before writing.
2. No hardcoded design values. Colors, spacing, radii, shadows, durations, easings — all from tokens.
3. Every interactive element has hover, active, focus-visible, and disabled states.
4. All motion respects prefers-reduced-motion.
5. Every image / illustration has alt text or aria-hidden if decorative.
6. Dark mode is never an afterthought — emitted alongside light from the start.
7. Stack-respect: never introduce a new framework or styling system; adapt to what's there.

1. Pick the chart from the question

Charts answer questions. Pick the chart from the question, never from the data shape.

When in doubt, a horizontal bar chart wins. It handles long labels, supports many categories, encodes a single number well, and is the most readable format. Full matrix in references/charts/chart-types.md.

2. Encoding — color is a last resort

Position is the strongest channel; length is next; angle/area are weak; color is the weakest. Encode the most important variable on the strongest channel available.

• A line chart already uses position (y) and length (x). Color distinguishes series; it does not encode magnitude.
• A bar chart uses length for magnitude; color should encode category, not redundantly encode magnitude (a single hue is fine).
• A heatmap is one of the few cases where color encodes magnitude — and only with a proper sequential or diverging scale.

Never use color as the only channel for an encoding. Pair with shape, pattern, or label.

3. Color palettes for charts

Three families, used for three jobs. Full token set in references/charts/color-encoding.md.

Hard rules:

• Max 8 categorical colors per chart. Beyond 8, group "Other" or change chart type.
• Colorblind-safe by default. Okabe-Ito or the Color Universal Design palette. Verify with a deuteranopia simulator before shipping.
• Red/green caveat. ~8% of men cannot distinguish them. If you need gain/loss, pair with arrow/sign and use --color-success-600 / --color-danger-600 only when the symbol carries the meaning.
• Single-hue sequential, not rainbow. Rainbow ramps lie about magnitude — they introduce false bands.

4. Axis honesty

Axis decisions are ethics decisions.

• Bar charts MUST start at zero. A bar's length encodes magnitude; truncating the axis makes a 2 % difference look like a 200 % difference. The most-shipped chart lie.
• Line charts MAY not start at zero. A line encodes change over time; forcing zero often hides the trend. Pick a baseline that frames the relevant variation, but show the baseline value clearly.
• Use log scale when the data spans > 2 orders of magnitude. Always label the axis as log explicitly.
• Dual y-axes are usually wrong. They imply correlation that often isn't there. Use small multiples instead.
• Time axes are linear in time, not in data points. Missing days exist; do not compress them out.
• Round axis ticks to human numbers (1, 2, 5, 10, 20, 50…) — never 2.347 ….

5. Annotations and reference lines

Numbers on a chart need context. Annotations carry that context.

• Reference line for goals, averages, prior period — 1 px dashed at --color-text-2, with a small label at the end.
• Threshold band for normal range — fill --color-surface-2 between bounds.
• Event markers — vertical line at a known event ("Launch", "Outage"), label on top.
• Callout — pin to a specific data point with a leader line; never more than 2 callouts per chart.

Annotations belong to the chart, not the page. They go inside the SVG so they survive export.

6. Tooltips

Tooltips supplement; they never carry primary information.

• Trigger on hover and focus. Touch devices: tap to pin, tap-elsewhere to dismiss.
• Content: x value (formatted, full date including year), one row per series with swatch + label + value, total when stacked.
• Position: above the cursor, flips below if it would clip the viewport. Never covers the data point.
• 150 ms delay on entry to avoid flicker; instant on exit.
• Tooltip must also be reachable via keyboard — arrow keys move the focused datum; the tooltip mirrors the focus.

A chart whose only legend is the tooltip is broken. Tooltips supplement an existing visible legend.

7. Legend placement

Inline labels at the end of each line beat any legend for line charts. Do this whenever space allows.

Interactive legends (click to toggle a series) are excellent — but the toggle state must persist for the session and be keyboard-reachable.

8. Accessible alt-text for charts

Every chart MUST have alt text. The pattern:

"[Chart type] showing [variable] over [domain]. [Headline insight]. [Range or notable point]."

Examples:

• "Line chart of daily active users from Jan to Mar 2026. Steady growth from 12k to 18k, with a dip on Feb 14."
• "Horizontal bar chart of revenue by region. North America leads at $4.2M, EMEA second at $2.8M, APAC third at $1.6M."

Beyond alt text, provide a "View as table" toggle on every chart. Screen-reader users, keyboard users, and analysts copying numbers all benefit.

<figure role="figure" aria-label="…">
  <svg aria-hidden="true">…</svg>
  <figcaption class="sr-only">[full description]</figcaption>
  <button aria-controls="chart-table">View as table</button>
  <table id="chart-table" hidden>…</table>
</figure>

9. Animation rules

Charts animate to communicate change, not to entertain.

• Entrance: 600 ms, ease-out-quint. Lines draw left-to-right; bars grow from baseline. Disable under prefers-reduced-motion.
• Update (data change, filter change): 300 ms, ease-in-out-cubic. Animate position, not opacity flicker. Respect reduced motion.
• Hover / focus highlight: 150 ms, ease-out-quint. No layout shift.
• Suppress animation when: the chart updates more than once every 2 seconds (live data); the user changes the time range (snap, don't morph); the dataset cardinality changes (a bar appearing from nothing reads as a glitch — fade in only).

Tokens: --dur-150 / 300 / 600, --ease-out-quint, --ease-in-out-cubic — see references/charts/chart-motion.md.

10. Responsive sizing and density

A chart that only works at 1440 is a screenshot. Three sizes for one chart:

Below 768 px:

• Drop minor gridlines.
• Move legend below or behind a toggle.
• Reduce tick density (every other tick).
• Charts in tabs / accordions on mobile, not stacked grids.

Sparklines have no tooltip; their context lives in the surrounding KPI tile (label + value + delta). Don't rebuild a chart inside a sparkline.

11. Library guidance — verify at build time

Per spec section 11, do not lock a chart library in the design. Detect what the project already uses; if none, present 2–3 candidates and selection criteria, then ask.

Detection order: read package.json → if a chart lib is present, use it. If not, ask the user. Never silently install. Match the constitution's stack-respect rule (rule 7).

12. Anti-patterns (do not generate)

• Bar chart with truncated y-axis. Always start at zero for bars.
• Pie chart with > 5 slices, or with slices that don't sum to 100%.
• Dual y-axis on overlapping lines (false-correlation hazard).
• Rainbow color ramp for sequential magnitude.
• 3D charts for 2D data. The third dimension is decoration; it distorts.
• Smoothed lines (monotone/spline) on time series — invents data points between actual values.
• A legend that's the only way to identify a series, plus no tooltip.
• Animation on a live-updating chart that thrashes the eye.
• A chart with no title, no axis labels, no source, and a tooltip carrying all of the above.
• Chart labels at angles other than 0° or 90°. Rotate the chart, not the labels.