Chart Color Audit

chart-color-audit

チャートのカラーパレットのアクセシビリティ監査です。数学でひとつの問いに答えます。 誰もがデータ系列を見分けられますか？

テキストのコントラストをチェックするツールはたくさんあります。このツールがチェックするのは、ダッシュボードで実際に問題になること、つまり色覚多様性があってもパレットを見分けられるかどうかです。公開されている Machado, Oliveira & Fernandes 2009 の行列を使って、1型色覚、2型色覚、3型色覚をシミュレーションし、OKLabで色のペアごとの距離を測定し、 WCAG 2.2 に基づいて背景とのコントラストをチェックします。変更によってこれらのいずれかが気づかないうちに損なわれた場合は、ビルドを失敗させます。

使い方は4通り。自分に合ったものを選んでください。

対象	目的	移動先
パレットを手元に持っているデザイナー	インストールなしですぐに判定したい	1 · パレットを試す
リポジトリにトークンがあるチーム	色の変更でアクセシビリティが損なわれたらビルドを失敗させたい	2 · CIに組み込む
ツールを構築するエンジニア	型付き関数として監査を利用したい	3 · コードから呼び出す
Claudeなどのエージェントを使う方	MCP ツールとして監査を利用したい	4 · エージェントに組み込む

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

この3色は、どの色覚シミュレーションでも明確に見分けられます。一方、オレンジは白に対して2.42:1で、チャートのマークに必要な最低値である3:1を下回っています。白地に淡い色の棒グラフを使うのは、ダッシュボードで昔からよくある問題です。このツールなら、数値で検出できます。

終了コード：0 は合格、1 は不合格、2 は入力不正です。 CIでの使い方はこれだけです。

出力の見方

ΔEは知覚上の色の距離（OKLab × 100）です。人間の目で色を見分けられる境界は、およそ2です。

判定	最小 ΔE	意味
明確に異なる	≥ 10	プロジェクターでの表示や、通りすがりの一瞥でも見分けられます
識別可能	≥ 2	注意深く見れば、系列を見分けられます
識別にはパターンが必要	< 2	色だけでは不十分です。破線や形状でも見分けられるようにする必要があります
衝突	≈ 0–1	この色覚の人には、2つの系列が同じ色に見えます

closest pairは、最も近い色になった2つのスロット（1から始まる番号）を示します。その2色を修正して再実行し、必要に応じて繰り返してください。

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の色構文を使用できます：hex、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に組み込む

依存関係を追加せずに、2つのファイルで設定できます。

ステップ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を実行し、パッケージスクリプトから呼び出してください。動作は同じです。

有名なパレットで試す

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

その赤と緑は、2型色覚のシミュレーションではΔ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

完全な型付けに対応しています。データ依存関係は2つです（色の計算にculori、サーバーにMCP SDKを使用）。DOMもネットワークも使いません。

4 · エージェントに組み込む（MCP）

会話の途中でエージェントに色を監査させます：

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

読み取り専用のツールが2つあります。audit_palette（色を貼り付ける）と audit_tokens （設定を指定する）です。「このパレットは白の上で色覚異常のある人にも安全ですか？」と尋ねれば、 感覚ではなく測定結果に基づく回答が得られます。

公式 MCP Registry に io.github.socraticstatic/chart-color-audit として登録されており、 Glamaにも掲載されています。

判定しきい値

モード	失敗条件	対象
perceptual（デフォルト）	いずれかのシミュレーションで、ペアのΔEが人間の知覚限界である2を下回る、またはコントラストが3:1未満	色だけで識別情報を伝えるパレット
redundant-encodings	明確な衝突のみ（通常時はΔE < 1／CVD時はΔE < 0.1）	すべての色にダッシュ／デカール／形状のチャンネルを組み合わせるデザインシステム
strict	通常時はΔE 10未満／CVD時はΔE 4未満	管制室、プロジェクター、廊下を通りすがりに見る用途

テキストトークンは、どのモードでも4.5:1でチェックされます。デフォルトのしきい値を変更する場合は 必ずメジャーバージョンの変更になります。パッチリリースでデフォルトの基準を厳しくすると、 CIゲートでビルドが失敗し、信頼も損なわれます。

対応範囲について

トークンを受け取り、指摘を返します。宣言されたパレットの色を監査するものであり、 グラフをレンダリングしたり、スクリーンショットのピクセルを解析したり、ページをクロールしたりはしません。 テキストのコントラストチェッカーは数多くあります。このツールが新たに提供するのは、ほかでは見つけられなかった 部分、つまりビルドゲートおよびMCPツールとしての、CVDシミュレーションによる系列の識別性です。

開発の経緯

このエンジンは、グラフのカラーシステム から切り出したものです。そのシステム自体の履歴が、この問題を実証しています。かつて「精度の修正」と称するコミットで、 正しい第二色覚異常の行列が、自信たっぷりで一見もっともらしい捏造値に置き換えられ、レビューも通過しました。 ピン留めした回帰テストだけがこれを検出できたはずです。そこで、このパッケージではテストスイートにおいて、 行列を公開論文の値に対して恒久的に固定しています。

全容はこちら：docs/POSTMORTEM.md：誤った行列が9週間使われた経緯、それを捏造したAIとの共同執筆コミット、そして現在、数学が数学を検証する理由。

コンサルティング

こうした失敗を対象に、ダッシュボードやデザインシステムを監査しています。 UXに携わって30年。上記の数式で指摘事項を証明できるため、議論に頼る必要はありません。[email protected]

MIT © Micah Boswell