令牌命名按角色与状态拼读,不按外观描述
别名: 角色状态命名 · 语义化命名 · color.bg.success
概念解释
公共名字应当能被读成一句职责:color.bg.success 是「成功这一角色的背景」,需要时再接状态,如 color.bg.success.pressed。color.green.600 读成的是颜料。颜料会换,角色还在。按角色与状态拼读(role-state naming)要求对外的令牌名回答「它在干什么、处于哪一态」,不回答「它看起来像哪块色板」。原始值层内部用颜料名可以;那一层不是给页面作者当公共 API 用的。页面作者若把 color.green.600 写进业务,品牌把成功改成别的绿、或改成不是绿的时候,每一次出现都是一句谎言或一次全库搜猎。
机制
名字是给几个月后不在设计文件里的人用的索引。外观名把索引钉在当下的样本上:今天成功是那级绿,明天不是,索引全部作废,但引用还在。角色名把索引钉在产品语义上:成功、危险、禁用、悬浮——这些词跟着任务走,不跟色板走。状态接在角色后面,是因为同一角色在默认、悬停、按下、禁用下取值不同,却仍是同一职责;把状态写成另一个颜料名(「更深的绿」),职责从名字里消失,调用方只能靠记忆或注释。拼读顺序(类别 · 角色 · 状态)让人不用打开文件就能排除错误:背景不会被当成描边,成功不会被当成危险。外观名做不到这种排除,因为它根本没说出类别和角色。
边界
原始值色板、字重轴、间距阶在最底层必须有不可再分的编号或颜料名,否则无处存放实际数值;禁止的是把这些名字提升为页面层的公共引用。插画和摄影里的颜色不是界面角色,不必强行叫 color.bg.success。数据可视化的序列色(第三条线、第七个扇区)常常没有产品角色,按序号或色相命名是诚实的;不要假装每条线都是「成功」。品牌专色若只出现在标志里,可以保留颜料名,前提是业务界面不准引用。多语言下角色词要选在代码里稳定的英文键,展示名另译;把中文「成功绿」写进键,重构和检索都会痛。
怎么落地
- 规定页面与组件实现只允许引用带角色的名字。颜料名、编号名留在原始值文件,不出现在业务拉取请求里。
- 新令牌先出声读:能否读成「某类别上的某角色,处于某态」。读成「那种绿」「稍微大一点」,退回改名。
- 改版时只改角色名背后的赋值,不改角色名。若发现必须改名,说明当初写的是外观,补一次重命名迁移。
- 验证:在业务仓库搜索
green、blue、#、具体字号数字作为令牌路径的一部分。命中即为外观命名泄漏。再抽十条公共令牌让未参与建设的工程师只看名字、说出它用在什么职责和哪一态;说成颜料或说不出态,名字就没有在承担索引。把成功色换成明显不同的赋值:所有仍叫*.success的调用应跟上,所有叫*.green.*的调用应暴露为漏网——后者就是这条命名规则要消灭的引用。