better-colors

颜色

此技能用于构建和审查颜色系统。它会生成色阶，将各级映射到角色和令牌名称，转换颜色表示法，并测量渲染后的对比度配对。

绝不要报告未经测量的对比度值，也绝不要估算可以计算出的颜色。颜色表示法、中性色的色调以及渐变的插值空间，都是项目的选择，并非检查结果。角色映射错误、未通过的配对以及超出色域的色阶，才是检查结果。全文所说的感知亮度均指 OKLCH L，范围为 0 到 1。

一组配对是否必须通过，属于 better-accessibility 的范畴。表面、阴影和图标颜色属于 better-ui 的范畴。

匹配项目的颜色系统

沿用项目的令牌和颜色表示法。统一使用 hex 的系统，胜过 hex 和 oklch() 混杂使用的系统。

对于新系统，oklch() 是最佳默认选择，因为它的数值特性符合下文的色阶规则。其他情况下，颜色库会以项目自己的表示法生成相同的色阶（color-formats.md）。

系统由色阶组成，而非单个颜色

只需一组中性色阶、一组强调色色阶，以及产品实际渲染的状态色阶。没有任何内容导入的 warning 色阶，只会增加维护成本，却不产生任何像素。只有当两种颜色必须一眼就能区分时，才值得增加第二种强调色。否则，应增加单组强调色色阶的级数。

每一级都有用途

色阶不是供人凭直觉挑选的渐变。每一级都因某个角色需要它而存在：页面背景、组件悬停状态、边框、纯色填充、正文文本。不要生成没有任何角色使用的级别。Tailwind 的 50–950 和 Radix 的 1–12 两种惯例都能映射到这些角色（palette-structure.md）。

基础令牌按色相命名，语义令牌按角色命名

基础令牌命名一个值（--blue-600），绝不直接用于组件。语义令牌命名一个用途（--color-text-secondary），指向一个基础令牌，也是组件唯一引用的层级。这个分界让主题可以在不触碰组件的情况下重新指向颜色（token-naming.md）。

令牌只能用于其对应角色

绝不要因为某个令牌今天的值合适，就挪作他用。用于分隔线的令牌若被用作文本颜色，等到边框变浅时，文本也会随之变浅。如果某个角色没有对应令牌，就添加一个。

在整个色阶中保持色相

色阶从头到尾都保持同一色相，在中间达到最高鲜艳度，并在较亮的一端采用更细的级差。应使用颜色库构建，绝不要凭直觉调整（palette-generation.md）。

一种颜色，一种含义

在整个界面中，一种颜色只用于一种目的；将 OKLCH 色相相差 15° 以内的颜色视为同一种颜色（color-usage.md）。绝不要只用颜色来传达含义。还要搭配图标或标签，这是 better-accessibility 的要求。

每个视图只用一种填充色强调操作

当纯色填充用于表达主要强调时，只给一个主要操作使用，其他同级操作保持中性。将颜色用于背景，而不是标签。纯色填充按钮远看就像主要操作；中性按钮上的强调色文本则像链接。

如果既有层级已通过其他方式表达强调，就应保留。多个彩色背景并无问题，只要它们表达的是不同状态或类别，而非相互竞争的同级操作。

测量渲染后的配对，再报告结果

测量前景色与其实际渲染所在背景之间的对比度，而不是与页面背景之间的对比度。如果某组配对未通过，应报告该配对、测得的数值以及未达到的阈值，然后不要改动颜色。颜色是设计决策。只有收到要求时才更改，并在更改后重新测量（contrast.md）。

为渐变选择插值空间

插值空间影响视觉效果，并非正确性设置。默认使用 in oklab；当双重色相渐变的中间部分变灰时，再使用 in oklch（color-usage.md）。

完成前检查

模式	修复方法
组件文件中存在十六进制、rgb( 或 oklch( 字面值，且已有对应令牌	按项目的表示法复用或添加角色令牌
代码库中其他颜色都用十六进制表示，却有一个 oklch( 值	除非正在进行迁移，否则按既定表示法编写
组件文件中有 var(--blue-600) 或 bg-blue-600	将语义令牌指向原始令牌，并使用该语义令牌
语义名称包含色相或组件，例如 --color-blue-button 或 --color-sidebar-gray	按角色重命名：--color-accent-solid、--color-bg-surface
同时定义了 --color-primary 和 --color-text-primary	将品牌令牌重命名为 accent
在 color: 中使用了 border 或 separator 令牌，或在 background: 中使用了 text 令牌	为缺失的角色添加令牌
hsl( 色阶值之间只有亮度不同	使用恒定的感知色相，按项目的表示法重新构建
50–200 之间的 OKLCH L 步进幅度与中间色阶的步进幅度一样大	缩小浅色端的步进幅度，每步约为 0.04–0.05
所有色相的色阶都复制使用同一个色度或饱和度数值	使用各色相自身最大值的相同比例
状态色相与强调色相相差不到 15°	至少拉开 15°，或为危险操作采用不同的样式
深色令牌只是浅色色阶按相反顺序排列	降低强调色的色度，扩大深色端的间距，并重新测量每一组颜色
在 prefers-color-scheme 和 .dark 类下都设置了颜色令牌	选定一种切换机制，并在各处统一使用
修复对比度时改变了色相，却保留了亮度	改变亮度；通道对比度对此有响应
在同一块规则中，prefers-contrast: more 为两种外观覆盖了同一个颜色	为每种外观分别设置对比度增强值
文字叠加在带透明度的颜色上，例如 /50、rgba( 或带有 transparent 的 color-mix(	测量渲染结果，或使用不透明令牌
Tailwind 500 填充色上使用了 text-white	测量对比度；白色文字在大多数 500 色相上的对比度达不到 4.5:1，因此将填充色改为 600
oklch() 色度超出 sRGB 范围，且之前未声明 sRGB 值	先声明 sRGB 值，再在 @media (color-gamut: p3) 内声明鲜艳版本

报告

严重级别。 HIGH 表示内容无法阅读，或语义颜色产生误导。MEDIUM 表示明显的主题、令牌或色域问题。LOW 表示局部细节问题。

无论出现在哪种界面上，以下三种症状一经发现都属于 HIGH，与 better-interface 的升级处理触发条件一致：正文或控件文本的实际渲染色彩对比度未达到要求；仅通过颜色表达状态或含义；语义颜色的用途与其含义不符。

验证。 无浏览器时：检查令牌值、每种已声明颜色的色域、两种主题块是否都存在，以及根据声明的令牌对计算出的对比度。有浏览器时：测量文本后方实际渲染的背景，包括透明度和其下方的任何图像，并分别测量浅色和深色主题。将所有无法执行的检查报告为 Not verified。

格式。 按违反的原则对发现的问题分组，并按严重级别排序；每个根本原因占一行，列出其出现的所有位置：

严重级别	位置	修改前	修改后	原因

Location 的格式为 path/to/file:line。Why 说明相关原则以及对用户的影响。

如果仍有任何 HIGH 问题，以 Block 结尾；否则以 Approve 结尾，并在表格中保留其余待处理事项。未检查的范围绝不可标记为 Approve。如果没有任何可报告的问题，请写明“No actionable color findings”，并报告验证结果。