chart-color-audit

Accessibility audit for chart color palettes. Answers one question with math: can everyone still tell your data series apart?

Plenty of tools check text contrast. This one checks the thing dashboards actually break: whether your palette survives colorblindness. It simulates deuteranopia, protanopia, and tritanopia with the published Machado, Oliveira & Fernandes 2009 matrices, measures pairwise separation in OKLab, checks WCAG 2.2 contrast against your background, and fails your build when a change quietly breaks any of it.

Four ways in. Pick yours.

| you are | you want | go to | |---|---|---| | a designer with a palette in hand | a verdict right now, nothing installed | 1 · Try a palette | | a team with tokens in a repo | the build to fail when a color change breaks accessibility | 2 · Gate your CI | | an engineer building tooling | the audit as a typed function | 3 · Call it from code | | working with Claude or another agent | the audit as an MCP tool | 4 · Wire it into an agent |

1 · Try a palette (nothing to install)

npx chart-color-audit --colors "#4E79A7,#F28E2B,#E15759" --bg "#fff"

chart-color-audit · 3 colors on #ffffff · mode: perceptual

  vision          min ΔE   closest pair   reading
  · normal          14.6   2 ↔ 3        clearly distinct
  · deutan          11.9   2 ↔ 3        clearly distinct
  · protan          11.9   1 ↔ 3        clearly distinct
  · tritan          10.3   2 ↔ 3        clearly distinct
  · achromatopsia    5.2   1 ↔ 3        distinguishable

  contrast vs background: worst 2.42:1 (slot 2, needs ≥ 3:1)
  ✗ slot 2 #f28e2b — 2.42:1

  FAIL — 1 finding:
    · contrast: slot 2 (#f28e2b) is 2.42:1 vs. background (needs ≥ 3:1, WCAG 2.2 SC 1.4.11).

Those three colors separate cleanly under every colorblind simulation. The orange still fails: 2.42:1 against white, below the 3:1 floor for chart marks. Pale bars on white is one of the oldest dashboard sins, and this is it, caught in numbers.

Exit codes: 0 pass, 1 fail, 2 bad input. That is the whole CI contract.

Reading the output

ΔE is perceptual color distance (OKLab × 100). About 2 is the edge of what a human eye can tell apart.

| reading | min ΔE | meaning | |---|---|---| | clearly distinct | ≥ 10 | survives a projector and a hallway glance | | distinguishable | ≥ 2 | a careful reader separates the series | | patterns carry identity | < 2 | color alone is not enough; dash/shape must carry it | | COLLISION | ≈ 0–1 | two series are the same color for these viewers |

closest pair names the two slots (1-based) that came nearest. Fix those two, re-run, repeat.

CLI

npx chart-color-audit --colors <list> --bg <color> [options]
npx chart-color-audit [--config chartaudit.config.json]
npx chart-color-audit mcp

| flag | what it does | |---|---| | --colors <list> | comma-separated palette, any CSS color syntax: hex, hsl(), rgb(), oklch(), named, raw triples ("222 47% 6%") | | --bg <color> | background the marks render on | | --mode <mode> | perceptual (default) · redundant-encodings · strict (see Floors) | | --config <path> | config file, default ./chartaudit.config.json | | --json | full result as JSON: verdict, failures[], perVision[], contrast[], semantic[], text[] | | --version, --help | the usual |

2 · Gate your CI

Two files, no dependencies added.

Step 1. Put chartaudit.config.json in your repo root, pointed at the tokens you already have:

{
  // Where your tokens live: a .css file (custom properties) or a
  // W3C design-tokens .json file. Optional; you can also write
  // literal colors directly in the fields below.
  "tokens": "src/index.css",

  // CSS selector whose block holds the variables. Optional, default ":root".
  "selector": ":root",

  // REQUIRED. Your data-series colors, in slot order.
  // Each entry is a literal ("#4E79A7"), a CSS variable name from the
  // tokens file ("--chart-cat-1"), or a dotted path into design-tokens
  // JSON ("chart.categorical.1").
  "categorical": ["--chart-cat-1", "--chart-cat-2", "--chart-cat-3"],

  // REQUIRED. The background your marks render on.
  "background": "--chart-bg",

  // Optional. Status colors, checked at 3:1 vs the background AND for
  // collisions against the palette: the classic silent failure where a
  // "positive" green KPI reads as data series 3 for deutan viewers.
  // Verdict semantics: "low-contrast" and "collision" FAIL the audit;
  // "cvd-risk" (collides with a slot only under CVD simulation) is
  // REPORTED but does not fail — semantic roles usually carry redundant
  // cues (position, icon, label). Treat cvd-risk as a review prompt.
  "semantic": { "positive": "--chart-positive", "muted": "--chart-muted" },

  // Optional. Tokens rendered as UI text (status labels, captions, table
  // numbers). Text needs 4.5:1 (SC 1.4.3), not the 3:1 mark floor.
  // Reusing mark tokens as text is the most common failure I have shipped:
  // one measured sweep found 111 instances of it in a single app.
  "text": { "positive": "--chart-positive-text" },

  // Optional. Floors preset, and per-floor overrides on top of it.
  "mode": "perceptual",
  "floors": { "minContrast": 3, "minTextContrast": 4.5 }
}

Step 2. Add the workflow:

# .github/workflows/chart-colors.yml
on: [push, pull_request]
jobs:
  chart-colors:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx chart-color-audit

Done. A token edit that breaks a floor now exits 1 with named findings, in the PR, before anyone screenshots anything.

Prefer a pinned dependency? npm i -D chart-color-audit and call it from a package script. Same behavior.

The famous-palette test

npx chart-color-audit --colors "#4E79A7,#F28E2B,#E15759,#76B7B2,#59A14F,#EDC948,#B07AA1,#FF9DA7,#9C755F,#BAB0AC" --bg "#fff"

That is Tableau 10, one of the most-shipped chart palettes on earth, on a white dashboard:

  ✗ deutan           0.7   3 ↔ 5        COLLISION
  ✗ protan           0.9   4 ↔ 10       COLLISION
  ✗ achromatopsia    1.6   2 ↔ 4        COLLISION
  ...
  FAIL — 8 findings

Its red and green sit ΔE 0.7 apart under deuteranopia simulation. Roughly 1 in 12 men has red-green color vision deficiency; for most of them, series 3 and series 5 on that chart are the same color. Nothing in code review catches this. Math does.

3 · Call it from code

npm i chart-color-audit

import { audit } from "chart-color-audit";

const result = audit({
  colors: ["#4E79A7", "#F28E2B", "#E15759"],
  background: "#ffffff",
  // optional: semanticRoles, textRoles, mode, floors
});

result.verdict;   // "pass" | "fail"
result.failures;  // human-readable reasons, empty on pass
result.perVision; // per simulation: minDeltaE, closestPair, band

Fully typed. Two data dependencies (culori for color math, the MCP SDK for the server). No DOM, no network.

4 · Wire it into an agent (MCP)

Let an agent audit colors mid-conversation:

claude mcp add chart-color-audit -- npx chart-color-audit mcp

Two tools: audit_palette (paste colors) and audit_tokens (point at a config). Ask "is this palette colorblind-safe on white?" and the answer comes back with measurements instead of vibes.

Floors

| mode | fails when | for | |---|---|---| | perceptual (default) | any pair lands below ΔE 2, the edge of human perception, under any simulation; or contrast < 3:1 | palettes where color alone carries identity | | redundant-encodings | outright collision only (ΔE < 1 normal / < 0.1 CVD) | design systems pairing every color with a dash/decal/shape channel | | strict | below ΔE 10 normal / ΔE 4 CVD | control rooms, projectors, hallway glances |

Text tokens are checked at 4.5:1 in every mode. Changing default floors is a major version, always: a CI gate that tightens defaults in a patch release breaks builds and trust.

Honest scope

Tokens in, findings out. This audits declared palette colors. It does not render charts, screenshot pixels, or crawl pages. Contrast checkers for text exist in plenty; what this adds is the part I could not find anywhere else: CVD-simulated series separation, as a build gate and an MCP tool.

Where this came from

The engine was extracted from a chart color system whose own history proves the point: an "accuracy fix" commit once replaced the correct deuteranopia matrix with confident, plausible, fabricated values, and review passed it. Only a pinned regression test would have caught it, so this package pins the matrices against the published paper in its test suite, permanently.

The full story: docs/POSTMORTEM.md: nine weeks of a wrong matrix, the AI-co-authored commit that forged it, and why the math now checks the math.

Consulting

I audit dashboards and design systems for exactly these failures. 30 years of UX practice, and the math above to prove findings instead of arguing them. [email protected]

MIT © Micah Boswell