design-token-contrast

用途

Design Token Contrast 用于在令牌层面检查项目颜色的可访问性对比度。它测量的是设计令牌而非屏幕像素：在令牌中修复一个问题，所有使用该令牌的地方都会同步修复。它适用于调色板变更、新增颜色、浅色或深色主题即将获批、用户询问某文本颜色在其背景上是否可读，以及无障碍审计标记出对比度问题并希望在令牌层面修复的场景。

主要能力

读取项目 CSS 自定义属性中的 --color-* 变量，支持 hex、rgb()、hsl() 或 oklch() 格式，可解析 var(--other) 引用。
区分默认主题与深色模式（prefers-color-scheme: dark、.dark 或 [data-theme=dark]）。
按名称配对令牌：文本令牌（text、foreground、link、focus 等）与背景令牌（background、bg、surface、card、canvas 等）。也识别西班牙语令牌名（texto、fondo、superficie、tarjeta）。
对每个配对输出 OK 或 NO，并给出对比度比值、最低要求和建议颜色。
对不达标的配对，建议保持相同色相、最接近的通过亮度颜色；并为每个令牌建议一个在其所有测量背景上都通过的值，使修复只需一次更改。
应用 WCAG 2.2 AA 最低标准：普通文本 4.5:1（1.4.3）、大号文本 3:1、UI 组件与图形（输入框边框、图标、焦点环）3:1（1.4.11）。

使用方式

检查器以源码形式提供，而非已提交的脚本。将 references/contraste-checker.md 中的 JavaScript 代码块保存为临时目录中的 contraste.mjs（无依赖，需 Node 18+），然后运行：

node contraste.mjs --tokens src/styles/tokens.css

不带 --tokens 时，它会查找 src/styles/tokens.css 及其他常见位置。

如果令牌名称不遵循默认配对模式，可将真实配对写入 JSON 文件并通过 --pares 传入（键为 texto、fondo 和 tipo，其中 tipo 为 texto 或 ui）：

[{"texto": "--color-gray-500", "fondo": "--color-white", "tipo": "texto"},
 {"texto": "--color-input-border", "fondo": "--color-white", "tipo": "ui"}]

--todos 会测量每种颜色与其他所有颜色的对比度，用于探索新调色板。--json out.json 将结果写入文件以便后续处理。脚本输出为西班牙语，但比值和令牌名在任何语言下含义相同。

脚本无法覆盖的情况需要人工检查：图片或渐变上的文本（截取该区域并检查最差位置）、带透明度的文本、令牌之外硬编码的颜色（搜索 #[0-9a-fA-F]{3,8}、rgb(、text-[#）、状态（hover、disabled——disabled 虽豁免但仍应可区分）以及承载信息的占位符。

报告与建议应包含：配对、当前值、最低要求、建议值、使用位置。通过搜索类和 var(--color-...) 引用来填写“使用位置”。

适用场景

调色板变更或新增颜色时。
浅色或深色主题即将获批时。
用户询问某文本颜色在其背景上是否可读时。
无障碍审计标记出对比度问题，希望在令牌层面修复时。

限制

它测量令牌而非渲染像素：图片、渐变和透明度需要视觉检查。
按名称配对是启发式方法；名称不常规时请使用 --pares。
该技能不能替代特定环境的验证、测试或专家审查。
检查器使用正则表达式而非浏览器 CSS 级联：作用域选择器、特异性、嵌套规则、层、导入和计算值可能被误读。应对照计算后的渲染样式审查显式配对。
每个测量主题内只寻求一个建议，不保证跨所有主题或背景。亮度在离散网格上搜索，色度可能被降低；不保证精确最近颜色，也不保证 sRGB 裁剪/舍入后色相不变。应用前应重新测量精确序列化颜色。
透明背景需要其实际底层合成；检查器会拒绝此类配对而非假定白色。
未解析的令牌会使覆盖不完整。轻量颜色解析器不是 CSS 验证器，无法认证颜色语法或色域映射。焦点要求还取决于状态/上下文及其他 WCAG 标准。
在批准的输入上运行前请阅读源码；报告输出使用独占私有文件创建，若目标已存在将失败。

安全与安全说明

脚本仅读取你指向的 CSS 或 JSON 文件，仅在带 --json 时写入文件。它不发起网络请求，不安装任何内容。需要 Node 18+。它从不自行编辑令牌；更改需用户批准后应用。

最佳实践

修复令牌一次，而不是逐个屏幕修补。
提供选项：加深令牌、仅将颜色用于大号文本，或为小号文本新增令牌（--color-accent-text）并保留原色用于填充和边框。
未经询问不要更改品牌色。
不要在没有检查深色模式的情况下报告某主题通过。

常见陷阱

问题：深色模式配对在浅色背景下显示 OK。解决：确保深色模式变量位于 prefers-color-scheme: dark、.dark 或 [data-theme=dark] 块中，以便脚本区分主题。

技能介绍

用途