Skip to main content
Glama

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

Related MCP server: Color Palette Generator MCP App

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, at or above the floor

color alone is not enough; dash/shape must carry it

COLLISION

below the floor

two series are the same color for these viewers

The floor depends on the mode (see Floors). In the default mode the floor is 2, so anything under 2 is a COLLISION and "patterns carry identity" only appears in redundant-encodings, where the floor is lower.

closest pair names the two slots (1-based) that came nearest. When more than one pair is under the floor, every one is listed beneath the table and in perVision[].failingPairs, closest first, so one run shows the whole repair.

achromatopsia is a grayscale check: Rec. 709 luminance, the view of a black-and-white print or a monochrome display. It is a floor for total loss of color, not a model of how the condition itself sees.

Translucent colors (rgba(), 8-digit hex, transparent) are measured as they render: composited over the background first. The background itself must be opaque.

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".
  // Another selector (".dark") is read on top of ":root", as the cascade
  // applies it.
  "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"). Aliases are followed: a CSS variable
  // set to var(--other) or hsl(var(--other)), and a token set to
  // "{other.token}".
  "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 }
}

Light and dark in one run

A palette that passes on white often fails on a dark background. Declare themes and each one is audited on its own; the run fails if any fails.

{
  "tokens": "src/index.css",
  "categorical": ["--chart-cat-1", "--chart-cat-2"],
  "background": "--chart-bg",
  "themes": {
    "light": {},
    "dark": { "selector": ".dark" }
  }
}

A theme may override any top-level key. semantic, text and floors merge key by key; every other key is replaced. A selector other than :root is read on top of :root, so a .dark block only needs the variables it changes. With --json a themed run prints { "verdict", "themes": { "<name>": <result> } }.

Series that touch

By default each series is checked against the background, not against its neighbors. For pie slices, or stacked bars and areas with no gap or stroke between them, the shared edge is what a reader has to see. Set a floor and every pair of series below it is a finding:

"floors": { "minPairContrast": 3 }

It is off (0) in every mode, because 3:1 between every pair is out of reach for a palette of more than a few colors, and a gap or a stroke between marks removes the need. The lowest pair is reported either way.

An unknown key in the config is an error, not a silent skip: a typo in semantic or text would otherwise drop the check it names.

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
      - uses: socraticstatic/chart-color-audit@v0.4.0

Done. A token edit that breaks a floor now fails the job with named findings, in the PR, before anyone screenshots anything. Each finding is an error annotation on the run, and the job summary carries the full table: every simulation, the closest pair with its hex values, and every slot below the contrast floor.

Action inputs

input

default

what it does

config

chartaudit.config.json

config file path; ignored when colors is set

colors

comma-separated palette, for a run with no config file

background

background for colors

mode

perceptual · redundant-encodings · strict; empty keeps the config's mode

fail-on-findings

true

false reports findings without failing the job

working-directory

.

where to run

version

the action's own release

npm version of chart-color-audit to run

cli

command to run instead of the npm package, e.g. npx --no-install chart-color-audit to use the version in your own package.json

Outputs: verdict (pass or fail) and findings (a count).

The action pins the npm package to the version it was released with, so a workflow pinned to a tag runs the same math every time.

Prefer no action at all? - run: npx chart-color-audit is the whole gate: exit 0 pass, 1 fail, 2 bad input. Or 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. One runtime dependency, culori for color math. The MCP server's own dependencies are bundled into the build, so an install is two packages. 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 read-only 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.

Listed in the official MCP Registry as io.github.socraticstatic/chart-color-audit and on Glama.

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. micah@conscious-shell.com

MIT © Micah Boswell

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables checking WCAG color contrast ratios and accessibility compliance between color pairs. Helps determine optimal text colors for backgrounds and validates color combinations meet accessibility standards.
      28 npm
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables users to generate color palettes (complementary, analogous, triadic, etc.) and check WCAG contrast ratios within AI chat applications using interactive UI.
      -
    • F
      license
      A
      quality
      C
      maintenance
      Checks whether a color palette or an image is colorblind-safe and names the pairs that collapse, generates colorblind-safe palettes, recolors images as protanopia/deuteranopia/tritanopia, and generates Ishihara-style test plates. Built on the published Machado 2009 + CIEDE2000 method and runs locally over stdio.
      6
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to work with color: converting between formats like HEX, OKLCH and Display P3, checking and fixing WCAG 2 and APCA contrast, auditing palettes for accessibility and color blindness, and generating palettes, gradients, scales and design tokens.
      18
      MIT