chart-color-audit
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 | |
a team with tokens in a repo | the build to fail when a color change breaks accessibility | |
an engineer building tooling | the audit as a typed function | |
working with Claude or another agent | the audit as an MCP tool |
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 mcpflag | what it does |
| comma-separated palette, any CSS color syntax: hex, |
| background the marks render on |
|
|
| config file, default |
| full result as JSON: |
| 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.0Done. 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 file path; ignored when |
| comma-separated palette, for a run with no config file | |
| background for | |
|
| |
|
|
|
|
| where to run |
| the action's own release | npm version of chart-color-audit to run |
| command to run instead of the npm package, e.g. |
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 findingsIts 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-auditimport { 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, bandFully 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 mcpTwo 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 |
| any pair lands below ΔE 2, the edge of human perception, under any simulation; or contrast < 3:1 | palettes where color alone carries identity |
| outright collision only (ΔE < 1 normal / < 0.1 CVD) | design systems pairing every color with a dash/decal/shape channel |
| 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Solve, audit and simulate colorblind-safe chart palettes. WCAG contrast, OKLab ΔE. Read-only.
Contrast checks with fixes, OKLCH harmonies, palettes, color-blind previews and code export.
WCAG color contrast checks, nearest accessible color, CSS color conversion and palette pair checks.
Run accessibility, contrast, and design token audits and file QA issues from your AI coding tool.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm2MIT
- FlicenseNot gradedqualityDmaintenanceEnables users to generate color palettes (complementary, analogous, triadic, etc.) and check WCAG contrast ratios within AI chat applications using interactive UI.-
- FlicenseAqualityCmaintenanceChecks 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-
- AlicenseAqualityCmaintenanceEnables 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.18MIT