如何使用语义色彩令牌

你的品牌使用绿色：主按钮是绿色，成功提示是绿色，选中的导航项也是绿色。一切看起来很协调，直到品牌改用紫色。上传成功的提示也该变紫吗？焦点轮廓呢？账户即将到期时旁边的警告又该怎么办？

语义色彩令牌（semantic color tokens）把这些决定明确下来。基础令牌用名称指向一个色值，例如 green-700；语义令牌则说明颜色的用途，例如 action-primary-background 或 status-success-text。组件引用的是用途，这样更新品牌时，就能修改应该跟随品牌变化的角色，而不至于误改所有使用相似色调的地方。

从想防止的错误开始

设想一个工作空间，其中有“创建项目”按钮、“已保存”确认提示、错误消息，以及一个被选中的侧栏链接。最初的设计师给按钮、确认提示和选中链接选用了相同的深绿色。开发者把这个色值只存储一次并复用，是很合理的实现。现在，新的品牌方向要求换一种主色。

一旦修改共用的绿色变量，这三个元素就会一起变化。实现方式与原有代码保持一致，但决策却错了：确认提示用绿色，是为了表达成功，而不是代表品牌的主要操作。这一区别原本存在于设计师的脑中，却没有进入可复用的规则。

在添加令牌之前，先用普通语言写下这个区别：“主要操作跟随产品品牌；成功反馈保留状态含义；选中项需要清楚的当前状态。”这些表述比一开始就规定命名格式更有价值，因为它们说明了哪些颜色值可以安全地一起变化。

Atlassian 如何让角色在界面中可见

Atlassian 的色彩指南在 Jira 看板上标出了选中状态、文字和品牌按钮背景所对应的令牌。它的术语区分了颜色角色、强调程度和交互状态，也把选中与键盘焦点分开处理：给选中元素加上焦点指示时，仍应保留其选中样式。

留意为什么带标注的界面比单独的调色板更有用。色块只能告诉你它的数值；看板则能展示体验中的哪一部分应该使用这个色值，以及原因。你可以直接判断标注指的是文字、表面还是图标，不必根据颜色有多鲜艳来猜测用途。

小型系统可以先借鉴这种做法，不必照搬整套命名清单。把拟定的令牌放到真实使用位置旁，描述什么情况应该使它变化，再举出一个它不该控制的用途。“品牌操作”和“操作成功”起初可以使用同一种绿色，同时仍是两个独立的决定。如果映射无法表达这个区别，它存储的只是调色板，而不是界面的语义。

把依赖测试具体化

一个小型别名映射，就足以暴露这个错误。下面的示例中，成功状态和主要操作起初使用相同色值，却分别引用不同的角色：

:root {
  --palette-green-700: #236646;
  --palette-purple-700: #6439a8;
  --action-primary-bg: var(--palette-green-700);
  --action-primary-fg: #fff;
  --status-success-text: var(--palette-green-700);
}
[data-brand="purple"] {
  --action-primary-bg: var(--palette-purple-700);
}

改变品牌属性后，使用 --action-primary-bg 的元素应该发生变化；使用 --status-success-text 的成功标签则不应改变。如果两者都变了，先检查组件实际引用了什么，再考虑换色；如果两者都没变，就检查是否存在写死的颜色，或优先级更高的覆盖规则。这是在测试依赖关系；这些示例色值放进真实场景后，仍然需要检查对比度。

接下来，把前景和背景一起测试。操作区域的底色与上面的标签是一对。 只更新底色，可能让原本可读的标签变得不合格，尤其是用更浅的品牌色替换深色时。应在映射中记录与之配对的角色，让其中一个变化时就触发对另一个的复查，而不是靠评审者自行记住。

分三轮检查迁移：

1. 先保持色值不变。 引入别名后，与原有视觉基线比较。出现意外差异，可能说明映射有误。
2. 临时改变一个角色。 检查所有预期使用它的元素，也检查本应保持不变的元素。
3. 恢复已批准的主题。 复查悬停、焦点、禁用和选中状态的组合。将有意保留的直接色值与尚未完成的迁移分别记录。

分开值、角色和组件决策

小型系统可以从两层开始：数值层保存实际颜色，角色层把这些数值映射到界面用途。如果某个组件需要独立演进，再增加第三个组件专属层会很有帮助，但不是每个小项目都必须有这一层。

例如，neutral-950 可以保存最深的中性色。text-primary 和 border-strong 起初都可能指向它，但它们仍然是不同角色，因为改善正文可读性，并不意味着每条强调边框都应该变深。今天数值相同，不能证明两个决定以后都应共用一个名字。

相反的错误，是给每个可见元素都创建独立令牌。如果普通正文段落都承担同一个角色，为每段正文各建一个文字令牌，只会增加维护工作，而不会增加含义。可以问：“我们是否可能有意只改其中一个用途，而不改另一个？”如果会，就考虑拆成不同角色；如果不会，就复用现有角色。

命名应当帮助人们正确选择，而不必逐个打开组件确认。开发者寻找输入错误的边框颜色时，不应该靠猜来判断 accent-strong、special-red 或 brand-secondary 中哪一个代表危险。宁可选容易理解的角色名称，也不要追求巧妙的缩写，尤其是同一份上下文还要交给编程智能体使用时。

把语义颜色映射到界面角色

先检查一个有代表性的页面，并查看它的几种状态。默认看板的静态截图，不会展示禁用操作、校验反馈、键盘焦点或选中的菜单项。你需要足够多的状态来找出真实的用色任务，而不是罗列大型组织未来可能支持的每一种理论状态。

对于这个虚构工作空间，第一版映射可以覆盖页面背景、抬高层级的表面、主要文字、次要文字、普通边框、主要操作、主要操作上的文字、选中、焦点、成功、警告和错误。有些角色需要前景与背景配对。浅色成功提示底色与上面的深色文字，使用不同的数值，却服务于共同的目的。

第一轮评审是梳理映射。标出示例页面中的每种可见颜色，询问它在传达什么。如果浅绿色面板只是把相关控件组织在一起，它属于表面或分组角色；如果它在宣告操作成功，它就属于反馈。两种用途可能看起来相似，但未来应按不同的规则变化。

把用途说明放在令牌名称旁边。“主要操作背景：一个章节中当前可用的最重要操作”，比只写“绿色”更有用。如果容易混淆，就加一个反例：这个令牌并不代表“所有希望用户注意到的元素”。重要的错误消息，仍然应使用恰当的反馈样式。

定案前，演练一次品牌改色

来看一个刻意缩小范围的例子。工作空间最初的品牌操作是绿色，成功反馈也是绿色。之后，操作色换成另一种品牌色。你希望按钮和选中导航的样式跟随新方向变化，而“已保存”仍保留容易辨认的成功角色。

先找出品牌决定影响了哪些角色。按钮背景与其前景文字需要一起复查；选中状态可能使用另一种由品牌色衍生的底色或指示；标志则是品牌素材，并非普通按钮令牌。不要通过通用界面规则给它重新着色，而不考虑它自身的素材要求。

接着，在页面副本中改变角色映射。不要搜索旧十六进制色值的每一次出现，然后无差别替换。搜索原始色值有助于找到候选位置，但它无法告诉你，某一次出现代表的是链接、成功状态，还是插图中的细节。

最后，检查所有使用已改角色的地方。主要操作可能出现在白色页面、浅色面板和对话框内部。在一个场景里很醒目的新底色，到了另一个场景可能融入背景。只有当这些预期用途仍然能传达正确操作，并保持可读时，映射修改才算完成。

明确状态，不必为所有情况都创造新颜色

默认外观只是操作行为的一部分。悬停、按下、获得焦点、选中和禁用，各自可能表达不同的信息。导航项可以在保持选中的同时获得键盘焦点；按钮可以有焦点，但并未被按下。不要把这些情况都压成一个“激活”颜色。

先确定每种状态必须传达的信息。悬停表明指针与元素的关系；焦点告诉键盘用户，接下来会在哪里发生交互；选中表示一个持续存在的选择。 这些视觉处理可以共用部分手法，但当状态同时出现时，仍必须能够区分。边框、下划线、图标或形状，都可以承担部分表达任务。

在侧栏示例中，可以采用轻微的选中底色，再配上清晰的焦点轮廓。不能因为某项已经选中，就让焦点轮廓消失。要直接检查两者共存的状态；只看孤立色块，无法判断两种处理会不会在真实组件中互相干扰。

禁用样式也需要同样认真地处理。如果用户不能自行判断为什么某个操作不可用，就需要解释。把按钮变灰，无法说明是缺少必填项、没有权限，还是操作已经在进行中。令牌只能命名一个视觉角色，不能替代交互逻辑或解释文案。

组件专属的例外应保持清楚可见。如果破坏性操作的确认需要不同的按钮样式，就记录其用途，不要悄悄在某个对话框里替换主要操作令牌。例外本身可能合理；真正的问题是，没人能判断它是刻意决定，还是一次性的实现捷径。

让颜色与可读的含义配合

颜色能帮助人们快速浏览界面，但即使难以区分色相，含义也必须成立。只有红色边框，会让用户自己猜哪里出了错；错误标签和有用的修正提示，才让状态容易理解。同样，成功图标配上“更改已保存”，也比一个没有标签的绿点传达得更多。

W3C 关于颜色使用的说明解释了为什么不能只依赖颜色传达信息或识别操作。应结合上下文，把这个原则应用到各个角色。在这个工作空间中，状态消息配有可读文字，选中项保留可见的选中样式，链接也不能只靠细微色差来辨认。

对比度是另一项独立检查。一个颜色可以传达正确含义，却仍然淡得难以阅读。应评估具体的前景与背景组合，而不是笼统地给一个品牌色块贴上“无障碍”的标签。浅色成功提示表面上的深色文字，与高饱和成功按钮上的白色文字，是两个不同的组合。

对于普通文字，WCAG 的最低对比度准则通常要求 4.5:1；符合条件的大号文字为 3:1，同时还有明确规定的例外。W3C 的对比度说明列出了适用范围和细节。应测量真实颜色组合及其渲染用途；一组通过，并不代表整个组件、主题或网站都已合格。

前面的示例色值能把这一点说明得更具体。按相对亮度计算，绿色 #236646 与紫色 #6439a8 对白色的对比度分别为 6.86:1 和 7.80:1；对黑色则分别为 3.06:1 和 2.69:1。因此，两种底色搭配白色标签都达到普通文字的门槛，搭配黑色则都未达到。这个结果不是由语义名称保证的，而是由具体前景和背景色值决定的。把计算结果与这一配对一起记录，未来品牌色变浅时，就能触发重新检查。

不要通过把整个界面都加深来修复所有问题。要找出失败的是哪个角色、位于什么表面、处于什么状态。次要文字同样承担阅读任务，过淡的帮助提示不会因为被称为“弱化样式”就变得更好。反过来，把每条分隔线都改成浓重深线，也可能抹掉这套系统本来要建立的层级。

把深色主题作为一套新映射来评审

深色主题是一次有用的压力测试，因为它能把目的与外观分开。主要文字仍然是主要文字，但数值会变化；抬高层级的表面仍须与页面区分；成功反馈即使前景和背景与浅色主题不同，也仍要容易理解。

不要只是反转每个基础色值，也不要直接把浅色主题数值搬到深色页面。需要重新检查彼此的关系：在白色背景上平衡的明亮操作色，到了深色表面可能过于抢眼；在浅面板上隐约可见的边框，也可能消失。图片、标志和图表还可能需要语义色彩映射之外的决定。

两种主题的预览要使用相同内容，否则内容密度或图片的差异，会分散对颜色决策的注意力。应纳入表单错误、成功消息、选中的导航项、有焦点的控件，以及部分次要文字。比较这些状态，比展示一组漂亮的默认按钮更有价值。

比较时，角色名称应保持稳定。如果你发现自己在深色主题中把 text-primary 改叫 white-text，就意味着把数值重新塞进了本应用来描述用途的名称。保持含义不变，改变为它服务的映射。

给编程智能体提供角色映射，而不只是调色板

要求智能体优化页面时，应同时提供视觉参考和角色决策。截图展示当前的颜色，却不能解释品牌变化时哪些颜色应继续联动，也不能说明哪些状态组合必须继续工作。一张简短的映射表，加一个代表性组件，能让这种意图更容易检查。

在 OpenDesign 支持的 HTML 预览中，可以查看渲染结果、使用可用的手动样式编辑控件，并在相关区域添加评论，作为对话上下文。用这些能力指出具体的不匹配，例如成功通知用了主要操作样式。反馈既要指出可见位置，也要说明预期角色。

例如，可以要求智能体更新主要操作映射，保留成功和错误角色，再展示受影响按钮在不同状态中的表现。如果现有项目已经有令牌约定，就提供相关文件或设计上下文。一次小范围的颜色修正，不必顺带要求建立全新的命名体系。

视觉修正之后，还应检查生成文件中组件实际引用的令牌。按钮可能看起来正确，却仍然使用成功令牌；下一次切换主题时，同一个依赖错误还会再次暴露。

先迁移一个代表组件

引入语义角色，不必一次替换整个网站。选一个具有多种有意义状态的组件，例如项目创建表单。列出当前色值，判断各自角色，再把角色映射到现有调色板。最初，视觉设计几乎可以保持不变。

接着，有控制地改变一个角色映射来测试。如果主要操作本应一起变化，就确认预期按钮确实跟着变了；如果状态消息应保持独立，就确认它们没有随操作色改变。测试关注的是依赖关系，而不是临时测试色是否适合作为最终品牌色。

记录仍在直接使用原始色值的地方。有些是刻意保留的：插图、合作伙伴标志或数据可视化，可能不属于相同的界面角色；另一些则是尚未完成的迁移。要标明区别，免得后来的人把未完成转换误认为已批准的例外。

代表性组件行为正确后，再扩展到相关组件。每完成一组有实质意义的迁移，就检查渲染后的页面，不要完全相信全局替换。共享规则可能影响你并未打开的场景。小步迁移能让你及时发现这些场景，而不至于等整个界面都难以比较时才发现问题。

一次有用的令牌评审应留下什么

最终评审应留下一份别人也能使用的映射：角色名称、预期用途、各受支持主题的当前色值，以及能展示行为的几个代表性组件。角色必须配对时，要补充说明，例如操作底色与其上的文字。记录有意义的例外，但不必为每一个像素单独制定政策。

请一位同事仅根据这份映射，为新的成功消息和新的主要操作选择令牌。如果不用看色块猜测就能选对，说明系统在发挥作用。如果两项选择最终仍都归结为“用品牌绿”，应先澄清角色说明，再添加更多令牌。