Data Visualization

A chart is read by people and executed by you. This skill turns "make it look

good" into a procedure with checks, so the result is right by construction rather

than by taste.

The method here is design-system-agnostic. Nothing in the procedure, the form

heuristic, the six checks, or the mark specs is specific to one product. A design

system supplies a small set of parameters (its ramps, a categorical order, a

diverging pair, a status palette, a texture, its surfaces, its filter components);

the method consumes them unchanged. A validated default palette is the

reference instance, fully specified in references/palette.md. To target your

brand, read that file's structure and substitute its values - touch nothing else.

The single most important habit: the color part is computable, so compute it.

Never eyeball whether a palette is colorblind-safe - run scripts/validate_palette.js.

The procedure - do these in order

Color comes LAST. Most bad charts pick colors first.

1. Pick the form. What is the data's job - magnitude, identity, polarity, a

single headline, change-over-time? The job picks the chart type, and sometimes

the answer is not a chart (a stat tile or hero number). -> references/choosing-a-form.md

1. Assign color by the job it does. Categorical (identity), sequential

(magnitude), diverging (polarity), or status (state) - each has one rule.

Assign categorical hues in fixed order, never cycled. -> references/color-formula.md

1. VALIDATE the palette - run the script, don't reason about Delta E.

node scripts/validate_palette.js "<hex,hex,...>" --mode light (relative to

this skill's base directory - or load it as <script type="module"> in the

chart's own page, where it reads

data-palette off <body> and logs a console.table report). It returns

pass/fail on the lightness band, chroma floor, adjacent-pair CVD separation,

the normal-vision floor, and contrast. Fix anything that FAILs before continuing. Re-run for

--mode dark with that mode's surface.

1. Apply mark specs & spacers. Thin marks, 4px rounded data-ends anchored to

the baseline, 2px lines, >=8px markers, a 2px surface gap between fills (stacked

segments and adjacent bars alike) and a 2px surface ring on overlapping marks,

selective direct labels. -> references/marks-and-anatomy.md

1. Add the hover layer - by default. An HTML/SVG chart is interactive; ship

a crosshair+tooltip on line/area and a per-mark hover tooltip on bar/dot/cell.

The only form that skips it is a bare stat tile with no plot. Hit targets bigger

than the mark; filters in one row above the charts. -> references/interaction.md

1. Final accessibility pass. For >= 2 series a legend is always present and <= 4

are also direct-labeled (a single series needs no legend box - the title names

it), so identity is never color-alone; a table view exists; dark mode is selected - its own

steps from the same ramps, validated against the dark surface, not an automatic

flip; texture is available for the CVD/print/forced-colors case.

1. Render it and look at it. The validator checks color, not layout - open or

screenshot the output and eyeball it for label collisions, geometry, and overflow

before calling it done.

Then check the result against references/anti-patterns.md - it is the catalog

of what goes wrong. If your chart matches an entry, it's wrong.

Non-negotiables (true in every design system)

• Assign categorical hues in fixed order, never cycled. A 9th series is never a

generated hue - it folds into "Other," small multiples, or composite encoding.

• One axis. Never a dual-axis chart (two y-scales). Two measures of different

scale -> two charts, small multiples, or indexed to a common base. *(This is the

#1 chart mistake - see anti-patterns.)*

• Color follows the entity, never its rank. A filter that changes the series

count must not repaint the survivors.

• **Sequential = one hue, light->dark. Diverging = two hues + a neutral gray

midpoint.** Never a rainbow; never a hue at the diverging midpoint.

• Run the validator before shipping any categorical palette. CVD Delta E >= 8 is the

target (OKLab ×100); 6-8 is a floor that is legal ONLY with secondary encoding. A

normal-vision floor below 15 is a hard FAIL - full-color readers can't tell the

pair apart; re-step it on the adjacent pairlist (secondary encoding does not excuse

this one); under --pairs all cut series or facet instead - see check 4. A contrast WARN

obligates visible labels or a table view - it is not dismissable.

• **Thin marks; a legend always present for >= 2 series (none for one), with

selective direct labels (never a number on every point); recessive grid/axes.**

• Text wears text tokens, never the series color - values, labels, and legends

stay in primary/secondary/muted ink; a colored mark beside them carries identity.

• Status colors are reserved (good/warning/serious/critical) and never reused

for "series 4"; they ship with an icon + label, never color alone.

Plugging in a design system

The method is invariant; only these parameters change per system. The reference

instance - every value filled in - is references/palette.md.

To onboard a new system: fill those rows, feed its ramps to the validator, and let

it snap each slot to the nearest passing step. Structure and rules stay as written.

Reference files