构建或审查项目颜色系统时用：用角色令牌…

当你为前端/UI 项目生成调色板、定义或使用颜色令牌、转换颜色格式、检查对比度或审查颜色实现时，按角色与色阶建立可验证的颜色系统。

适用场景

解决思路

1. 把颜色系统视为一小组按角色命名的色阶，并针对它们实际渲染的背景进行验证；多数颜色 bug 是系统 bug，孤立选值、因看起来合适而借用令牌、无人测量过的配对都会引入问题。
2. 永不报告未实测的对比度，永不估算可计算的颜色；颜色是界面中少数有精确答案的问题，必须给出精确答案。
3. 明确边界：对比度要求归 better-accessibility；表面、阴影和图标颜色归 better-ui。
4. 匹配项目颜色系统：复用项目现有令牌与记法；不要为修正一个值而引入第二种表示；一致的 hex 系统优于 hex 与零散 oklch() 混用。
5. 新建颜色系统时，优先使用 oklch() 作为默认，因为其数值行为符合下面的色阶规则；其他情况下用颜色库按项目自身记法生成同样的色阶，参见 color-formats.md。
6. 把系统看作色阶而非单个颜色：只建一个中性色阶、一个强调色阶，以及产品实际渲染的状态色阶；不导入的 warning 色阶是零像素维护；只有当两个事物必须一眼区分时才增加第二个强调色相。
7. 让色阶每一步都有职责：不要按眼睛从渐变中挑颜色；每一步都因角色需要而存在，如页面背景、组件 hover、边框、实心填充、正文文本；不要生成没有角色消费的步骤；Tailwind 50–950 与 Radix 1–12 约定都映射到这些角色，参见 palette-structure.md。
8. 原始令牌按色相命名，语义令牌按角色命名：原始令牌命名值（--blue-500）且绝不在组件中使用；语义令牌命名职责（--color-text-secondary）、指向原始令牌，并且是组件唯一引用的层级。
9. 保留原始令牌与语义令牌之间的接缝：它让主题化成为可能；没有它，深色模式意味着审计每个用法来判断哪些表示“强调色”、哪些只是想要蓝色，参见 token-naming.md。
10. 只在对应角色中使用令牌：不要因为某个令牌今天的值合适就借用；分隔线用作文本色，在边框变浅后文本也会跟着出问题；若某角色没有令牌，新增该令牌。
11. 在整个色阶中保持色相：合格色阶有四个属性——步骤在感知亮度上均匀变化，而非格式所称的亮度；色相从头到尾保持不变；鲜艳度在中段达到峰值并向两端衰减；步骤在浅端比深端更密集。两端都不要到纯黑和纯白，因为它们无法承载色相；用颜色库而不是肉眼判断，参见 palette-generation.md。
12. 一种颜色只赋予一种含义：在整个界面中一种颜色只用于一个目的，色相差 15° 以内视为同一种颜色；如果强调色表示可交互，该色相出现在静态文本上就会提示用户点击不可点击的东西，交互元素呈中性也会同样误导；颜色绝不能是唯一的意义载体，这由 better-accessibility 负责。
13. 每个视图只填充一个操作：当填充色编码主要强调时，只给一个主要操作使用它，同类操作保持中性；把颜色放在背景而非标签上；填色按钮远看就是主要操作，中性按钮上的强调色文字读起来像链接；当多个彩色背景编码不同状态或分类而非作为同级竞争时，可以同时存在。
14. 测量实际渲染的配对再报告：测量前景与其实际渲染背景，而非页面背景；当配对失败时，报告该配对、实测值和未达阈值，然后不要改颜色；这是设计决策，只有被要求时才改，改后重新测量，参见 contrast.md。
15. 选择渐变的插值空间：空间是视觉效果，不是正确性设置。`in oklab` 是最佳默认：亮度均匀、无意外色相。`in oklch` 沿色相轮而非中间路径行进，保持鲜艳并扫过停靠点之间的每个色相；当双色渐变中间变灰时用它。sRGB 默认会让中点变暗、变灰，这是大多数界面已有的效果，因为不指定时就会得到它，参见 color-usage.md。
16. 完成前检查并修复：项目已有令牌却用原始值 → 复用或新增角色令牌，并使用项目记法。
17. 完成前检查并修复：在 hex 代码库中塞入孤立 oklch() 值 → 除非迁移在范围内，否则保留既有记法。
18. 完成前检查并修复：在组件中直接使用 --blue-500 这类原始令牌 → 让语义令牌指向它。
19. 完成前检查并修复：令牌按外观命名（--color-blue-button）或首次用途命名（--color-sidebar-gray） → 按角色命名：--color-accent-solid、--color-bg-surface。
20. 完成前检查并修复：--color-primary 表示品牌而 --color-text-primary 表示正文文本 → 保留 accent 表示品牌；让 primary 表示“其组内最突出者”。
21. 完成前检查并修复：语义令牌用在其角色之外（分隔线当文本） → 为缺失角色新增令牌；绝不按值借用。
22. 完成前检查并修复：通过改变 HSL 亮度构建色阶 → 用感知亮度和恒定色相重建。
23. 完成前检查并修复：色阶在整个范围均匀间隔 → 收紧浅端，直到 50 和 100 读起来像两个表面。
24. 完成前检查并修复：不同色相复用同一饱和度数值 → 匹配各色相自身最大值的比例，而不是原始数值。
25. 完成前检查并修复：状态色相与强调色相冲突 → 移动它，直到 destructive 和 primary 并排可区分。
26. 完成前检查并修复：通过机械反转浅色调色板制作深色模式 → 反转作为起点，然后降低鲜艳度、放宽深端并重新检查每一对。
27. 完成前检查并修复：prefers-color-scheme 设置一些令牌而 .dark 类设置另一些 → 选择一种切换机制并贯穿使用。
28. 完成前检查并修复：通过改变色相修复对比度 → 改变亮度，即对比度响应的通道。
29. 完成前检查并修复：P3 颜色没有 sRGB 回退 → 先声明 sRGB 值，再在 @media (color-gamut: p3) 内覆盖。
30. 报告严重性：HIGH 使内容不可读或赋予误导性语义颜色；MEDIUM 是明显的主题、令牌或色域失败；LOW 是孤立打磨问题。
31. 验证：无浏览器时，检查令牌值、每个声明颜色的色域、两个主题块都存在，以及从声明的令牌配对计算对比度；有浏览器时，检查文本实际渲染的背景，包括透明度和其下任何图像，并在浅色和深色下都测量；失败的配对要报告，而不是重新上色；每个无法运行的检查都报告为 Not verified。
32. 报告格式：按违反的原则分组，按严重性排序，每个根因一行，列出它出现的每个位置：| Severity | Location | Before | After | Why |；Location 为 path/to/file:line；Why 说明原则和用户影响。
33. 结尾：任何 HIGH 仍存在时给 Block，否则给 Approve，其余留在表中作为待办；绝不要 Approve 你未检查的覆盖范围；没有可报告内容时，声明 “No actionable color findings” 并报告验证。

适用边界 · 注意事项

• 对比度合规判定本身属于 better-accessibility；若任务是无障碍标准审计，应与该技能配合，而不是只靠本经验。
• 表面、阴影、图标颜色属于 better-ui；这些领域不应仅靠本经验处理。
• 无法访问浏览器且必须确认实际渲染背景（透明度、下层图像）时，只能将相关检查标为 Not verified，不能给出最终 Approve。