CSS 设计令牌对比度矩阵 — 批量检测所有前景/背景对的 WCAG AA / AAA 合规性

真实使用场景

• 设计师在移交工程师之前审计完整令牌集

  你做了一套 30 个颜色的设计系统调色板，即将把令牌交给开发团队。粘入 CSS :root 代码块，选文字令牌为前景、面板令牌为背景，矩阵立刻标出六对不过的配对， 包括卡片背景上的灰色标签色。你调整三个令牌的明度，重新粘贴，交给工程师的是每对 实际出现的配对都已 AA 合规的令牌集，而不是留到 QA 阶段才发现问题。

• 开发者验证深色主题令牌是否满足 WCAG AA

  你的设计系统同时发布了浅色和深色主题 JSON 文件。你粘入深色主题令牌，选前景文字 令牌对比背景面板令牌，矩阵一眼扫完。大多数配对过 AAA。高层卡片面板上的次要 文字只到 3.8:1，仅大字 AA。你把该令牌加深一步，复制新的 hex，更新 JSON 文件， 在下次设计评审前提交修复。

• 无障碍顾问为 VPAT 报告审计客户令牌文件

  客户在无障碍审计前发来一份 Figma-Tokens JSON 导出。你直接粘入这个工具，嵌套的 `{"value": "#hex"}` 格式被自动识别，得到一张所有颜色令牌组合的矩阵。截图标红 的不过格子，记录每个违反了哪条 WCAG 标准（AA 普通文本、AA 大字、AAA），把矩阵 图贴进 VPAT 报告作为证据。整个分析不到一分钟，而不用一对一对手动检查。

常见踩坑

• 把所有令牌都同时选为前景和背景，会生成一张充满无意义格子的 N×N 矩阵（比如两个背景面板色互相对比）。预先筛选：文字令牌放前景，面板令牌放背景。

• 相信从 Figma 导出的带透明度或合成图层的 hex 值。本工具评的是纯色对纯色的对比度；如果实际渲染颜色是半透明叠层，真实对比度可能低于原始令牌值。

• 只修复直接不过的格子，忽略"仅大字 AA"（橙色）格子。仅大字 AA 对 ≥ 24px 的标题合格，但对 16px 正文不合格；矩阵标橙的配对，只有在能保证永远不用于小文字时才安全。

隐私说明