better-colors

颜色

颜色系统是一组精简的色阶，按角色命名、一致应用，并针对实际呈现它们的背景进行验证。几乎所有颜色问题都是系统问题：孤立选择一个值、因为看起来合适就借用一个令牌，或使用一对未经测量的颜色。对比度要求属于 better-accessibility；表面、阴影和图标颜色属于 better-ui。

快速参考

类别	适用场景	参考
结构	系统需要哪些色阶、各阶的角色、中性色、状态颜色、审查现有调色板	palette-structure.md
生成	从品牌色构建色阶、多色相系统、深色模式	palette-generation.md
命名	原始和语义层级、角色清单、命名语法、反模式	token-naming.md
用法	每种颜色表达一种含义、强调、渐变、文化、外观变体	color-usage.md
对比度	APCA 和 WCAG 检查、报告失败项、按需修复	contrast.md
格式	选择表示法、转换、色域和 P3 回退方案	color-formats.md
审查输出格式	严重程度量表、发现项表格、验证、结论	review-output.md

核心原则

1. 与项目的颜色系统保持一致

复用项目现有的令牌和表示法。为了修正一个值而引入第二种颜色表示方式，只会让调色板更难理解，而不是更简单——一致使用十六进制系统，胜过在十六进制系统中零散使用 oklch()。表示法本身并非缺陷。对于真正全新的系统，oklch() 是最佳默认选择，因为它的数值表现符合下文描述的色阶规则；其他情况下，颜色库都能按项目使用的格式生成相同的色阶（color-formats.md）。

2. 系统由色阶构成，而非零散的颜色

一组中性色阶、一组强调色阶，以及产品实际呈现所需的状态色阶。没有任何内容导入的 warning 色阶只会带来维护负担，却不影响任何像素；只有当两种事物必须一眼区分时，第二种强调色相才有存在的必要。

3. 每一阶都有用途

色阶不是供人凭眼睛挑选的渐变。每一阶的存在都应服务于某个角色——页面背景、组件悬停态、边框、纯色填充、正文文本——没有任何角色使用的阶就不应生成。Tailwind 的 50–950 和 Radix 的 1–12 约定都对应这些角色（palette-structure.md）。

4. 原始令牌按色相命名，语义令牌按角色命名

原始令牌命名一个值（--blue-500），且绝不直接应用于组件。语义令牌命名一项用途（--color-text-secondary），指向一个原始令牌，并且是组件唯一引用的层级。正是这层衔接让主题化成为可能；没有它，深色模式就意味着审查每一处用法，弄清哪些原本表示“强调色”，哪些只是需要蓝色（token-naming.md）。

5. 只在令牌对应的角色中使用它

不要仅仅因为某个令牌当前的值合适就借用它。将分隔线令牌用作文本颜色，在边框变浅时就会出问题，文本也会随之变浅。如果某个角色没有对应的令牌，就添加一个。

6. 色阶中保持色相一致

色阶的步进应在感知亮度上均匀，色相从头到尾保持恒定，鲜艳度在色阶中段达到峰值、向两端递减，且浅色端的阶距应比深色端更密。色阶两端都不要到纯黑或纯白，因为它们完全无法承载色相。请使用颜色库，而非凭眼睛估算（palette-generation.md）。

7. 一种颜色，一种含义

在整个界面中，让一种颜色只表示一种用途，并将色相相差 15° 以内的颜色视为同一种颜色。如果强调色表示可交互，那么将该色相用于静态文本，会让用户以为某个不可点击的内容可以点击；而将可交互元素渲染为中性色也同样会造成误导。颜色绝不能是传达含义的唯一方式；这一要求由 better-accessibility 负责。

8. 每个视图恰好突出一个操作

当填充色用于表示主要强调时，只将其用于一个主要操作，其他同级操作保持中性。将颜色用于背景，而不是标签：填充按钮远看也能呈现主要操作的感觉，而中性按钮上的强调色文本则会让人觉得是链接。如果多个彩色背景表示的是不同状态或类别，而不是相互竞争的同级操作，则可以同时使用。

9. 测量实际渲染的颜色对，然后报告

测量前景色与其实际渲染时所处的背景色之间的对比，而不是与页面背景色之间的对比。如果某个颜色对未达标，就报告它——包括该颜色对、测量值和未达到的阈值——并保持颜色不变。项目的颜色属于设计决策；只有在收到要求时才更改，并在更改后重新测量（contrast.md）。

10. 选择渐变的插值空间

插值空间决定视觉效果，而非正确性设置。in oklab 是最佳默认选项——亮度均匀，不会出现意外的色相变化。in oklch 会沿着色相环过渡，而不是穿过中心，因此能保持鲜艳，并扫过色标之间的色相：这是一种独特的视觉效果，也是双色相渐变在中间变灰时的解决方案。sRGB 默认插值则是经典选择，其较暗、较柔和的中间色也是大多数界面原本呈现的效果（color-usage.md）。

常见错误

错误	修正方法
项目已有设计令牌，却使用原始值	复用或添加符合项目现有命名规范的正确角色令牌
在使用十六进制代码的代码库中，单独插入 oklch() 值	除非当前任务包含颜色系统迁移，否则保留既有表示法
在组件中直接使用 --blue-500 这类基础值	让语义令牌指向该值，并使用语义令牌
令牌按外观命名（--color-blue-button）或按首次用途命名（--color-sidebar-gray）	按角色命名：--color-accent-solid、--color-bg-surface
--color-primary 表示品牌色，而 --color-text-primary 表示正文文本	将 accent 保留给品牌色；让 primary 表示“同组中最突出的”
在角色范围之外使用语义令牌（例如将分隔线令牌用于文本）	为缺失的角色添加令牌；绝不要借用数值相同的令牌
通过改变 HSL 明度来构建色阶	根据感知明度重新构建，并保持色相不变
色阶在整个范围内均匀分布	缩小浅色端的间距；50 和 100 必须能区分为两种表面颜色
在不同色相间复用相同的饱和度数值	匹配各色相自身最大值的相同比例，而不是相同的原始数值
状态色相与强调色相冲突	调整状态色，直到破坏性操作和主要操作并排时也能区分
通过机械地反转浅色调色板来创建深色模式	先反转作为起点，再降低鲜艳度、拓宽深色端，并重新检查每个颜色对
一部分令牌由 prefers-color-scheme 设置，另一部分由 .dark 类设置	选择一种切换机制，并在整个项目中统一使用
对比度不达标	报告该颜色对、测量值和未达到的阈值；只有在收到要求时才更改颜色
通过更改色相修复对比度	更改明度——对比度取决于这个通道
使用 P3 颜色，却没有 sRGB 回退值	先声明 sRGB 值，再在 @media (color-gamut: p3) 中覆盖
色相相反的渐变在中间变灰	切换到极坐标空间（in oklch），或在两种色相之间添加一个中间色标
只在浅色模式下验证调色板	在两种外观模式下重新检查每个前景色与背景色的颜色对

报告

当所有已确认的问题都按照 review-output.md 中的格式报告，并附有验证结果和结论时，独立的色彩审查即告完成。在 better-interface 中，则以其格式为准。