Data Visualization

references/palette.md

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

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

2. 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

3. 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.
4. 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

5. 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

6. 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.
7. 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.

references/anti-patterns.md

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 x100); 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

references/palette.md

interaction.md

Reference files

references/choosing-a-form.md

references/color-formula.md

references/marks-and-anatomy.md

references/interaction.md

references/components.md

references/anti-patterns.md

references/palette.md

scripts/validate_palette.js