Chart Color Audit

chart-color-audit

图表色板无障碍审计。用数学回答一个问题： 每个人都能区分你的数据系列吗？

许多工具会检查文本对比度。这个工具检查的是仪表板真正容易出问题的地方：你的色板能否经受色盲影响。它使用已发表的 Machado, Oliveira & Fernandes 2009 矩阵模拟绿色盲、红色盲和蓝黄色盲，以 OKLab 衡量成对色差，检查与背景之间是否符合 WCAG 2.2 对比度要求，并在改动悄悄破坏任一项时让构建失败。

四种使用方式，选一种。

你是	你想要	前往
手头有一套色板的设计师	立刻获得评估结果，无需安装	1 · 试用色板
在仓库中管理设计令牌的团队	颜色改动破坏无障碍性时让构建失败	2 · 在 CI 中设门禁
构建工具的工程师	将审计作为类型化函数调用	3 · 在代码中调用
使用 Claude 或其他 Agent 的人	将审计作为 MCP 工具使用	4 · 接入 Agent

1 · 试用色板（无需安装）

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

这三种颜色在所有色盲模拟下都能清晰区分。橙色仍未通过：与白色背景的对比度为 2.42:1，低于图表标记的 3:1 下限。白底上的浅色柱形是仪表板中由来已久的问题，而这次，数字把它揪了出来。

退出码：0 通过，1 未通过，2 输入无效。 CI 的约定就这么简单。

解读输出

ΔE 表示感知色差（OKLab × 100）。约 2 是人眼能够分辨的临界值。

结果	最小 ΔE	含义
清晰可区分	≥ 10	投影展示或匆匆一瞥时也能分辨
可以区分	≥ 2	仔细阅读时可以区分各系列
需要图案辅助识别	< 2	仅靠颜色不够；必须用虚线或形状辅助区分
COLLISION	≈ 0–1	对这些观察者来说，两个系列的颜色相同

closest pair 会指出距离最近的两个槽位（从 1 开始编号）。修好这两个，再次运行，如此重复。

CLI

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

标志	作用
--colors <list>	逗号分隔的色板，支持任意 CSS 颜色语法：十六进制、hsl()、rgb()、oklch()、命名颜色、原始三元组（"222 47% 6%"）
--bg <color>	标记渲染所用的背景色
--mode <mode>	perceptual（默认）· redundant-encodings · strict（参见下限）
--config <path>	配置文件，默认为 ./chartaudit.config.json
--json	以 JSON 格式输出完整结果：verdict、failures[]、perVision[]、contrast[]、semantic[]、text[]
--version、--help	常规选项

2 · 在 CI 中设门禁

只需两个文件，无需添加依赖。

步骤 1。 在仓库根目录中放入 chartaudit.config.json，指向你已有的设计令牌：

{
  // 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 }
}

步骤 2。 添加工作流：

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

完成。现在，如果修改设计令牌导致未达到下限，命令就会以退出码 1 结束，并在 PR 中列出具体问题；这一切都发生在有人截图之前。

更倾向于固定依赖版本？运行 npm i -D chart-color-audit，然后从 package 脚本中调用。行为相同。

知名色板测试

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

这是 Tableau 10——全球使用最广泛的图表色板之一——在白色仪表板上的表现：

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

在绿色盲模拟下，红色和绿色的 ΔE 仅相差 0.7。约每 12 名男性中就有 1 人患有红绿色觉缺陷；对其中大多数人来说，该图表中的系列 3 和系列 5 颜色相同。代码审查无法发现这一点，数学可以。

3 · 在代码中调用

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

具备完整类型。只有两个数据依赖（用于颜色计算的 culori 和 MCP SDK）。没有 DOM，也不访问网络。

4 · 将其接入 Agent（MCP）

让 Agent 在对话过程中审核颜色：

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

两个只读工具：audit_palette（粘贴颜色）和 audit_tokens （指定配置文件）。询问“这个调色板在白色背景上对色盲用户是否安全？”， 得到的回答会提供测量结果，而不是主观感受。

已列入官方 MCP 注册表， 名称为 io.github.socraticstatic/chart-color-audit，也已收录于 Glama。

阈值

模式	失败条件	适用场景
perceptual（默认）	在任何模拟条件下，任意一对颜色的 ΔE 低于 2（人眼感知的边缘阈值）；或对比度 < 3:1	仅靠颜色区分身份的调色板
redundant-encodings	仅在发生明显冲突时失败（正常视觉下 ΔE < 1 / CVD 下 < 0.1）	为每种颜色都配有虚线／贴花／形状通道的设计系统
strict	正常视觉下 ΔE < 10 / CVD 下 ΔE < 4	控制室、投影仪、走廊里的匆匆一瞥

所有模式下，文本令牌均按 4.5:1 的对比度检查。更改默认阈值 始终属于主版本更新：如果在补丁版本中收紧默认值，会导致 CI 门禁破坏构建并损害信任。

明确范围

输入令牌，输出审核结果。此工具审核声明的调色板颜色，不会 渲染图表、分析截图像素或爬取网页。文本对比度检查工具并不少见； 本工具新增的是我此前未曾找到的能力：将经过 CVD 模拟的系列区分度 作为构建门禁和 MCP 工具进行检查。

项目缘起

此引擎提取自一个 图表配色系统； 该系统自身的历史就证明了这一点：一次“准确性修复”提交曾用看似可信、 实则捏造的数据替换了正确的绿色盲模拟矩阵，评审也放行了。只有固定的 回归测试才能发现这个问题，因此本软件包在测试套件中永久固定了与已发表论文 一致的矩阵。

完整故事：docs/POSTMORTEM.md：九周的错误矩阵、 由 AI 共同撰写且捏造数据的提交，以及如今数学如何验证数学。

咨询服务

我为仪表板和设计系统审核此类问题。 我拥有 30 年 UX 实践经验，并能用上述数学结果证明发现的问题，而不是 靠争论说服对方。[email protected]

MIT © Micah Boswell