组件级令牌只服务单一组件,不对外复用
别名: 组件令牌 · 私有令牌 · private component tokens
概念解释
button.bg.hover 描述的是按钮这块解剖上、悬停这一态的背景。它不是「一种稍深的表面色」,尽管此刻它的值可能碰巧和某张卡片的悬停色相同。组件令牌(component token)的读者只有这一个组件的实现;卡片、输入、导航去读它,就是在偷用别人的骨头。跨组件要共享的值,走语义别名或更下面的原始值,不走组件令牌。组件令牌对外复用,下一次只改按钮,卡片会跟着变——爆炸半径被悄悄放大到「所有曾经图省事的调用」。
机制
组件令牌编码的是解剖位置:哪个零件、哪种态。解剖是组件私有的,零件名字在别的组件里并不存在或并不同位。读取它的外组件等于声明「我的这块等于按钮的那块」。按钮一旦改自己的悬停(对比度、品牌、按压分离),所有声明过等同的表面一起改,其中多数从未同意过这次改动。共享应当发生在「角色」上:成功背景、危险描边、悬浮层——这些名字不属于任何一个组件。组件令牌的私有性把一次组件改动的爆炸半径钉死在该组件内部。打破私有性,爆炸半径变成「谁图方便引用过」,而这份引用清单通常没有人维护。图方便的动机很强:值看起来一样,少声明一个名字。一样是此刻的快照,不是契约。
边界
同一组件的子零件之间共享组件令牌是合法的:按钮的标签和按钮的图标都读 button.fg.default,仍在一个爆炸半径里。跨产品复制同一组件实现时,令牌文件可以随组件走,那是在分发这个组件,不是外组件在引用。主题切换若被做成「重写 button.」,外组件读 button. 会把主题泄漏成按钮主题;主题应改语义别名。文档示例若把组件令牌写成可复制的公共色板,读者会当公共 API 用——示例必须标明私有。原子色板(原始值)本来就是给许多组件读的,不在这条禁令里;禁的是把带解剖名字的那一层当成色板。
怎么落地
- 组件令牌放进该组件的私有文件或私有命名空间,构建时不导出给业务仓库。业务代码引用
button.*应编译失败。 - 发现两处「值碰巧相同」,在语义别名层补一个角色名,让两处都改读角色,而不是让卡片改读按钮。
- 代码评审把跨文件引用组件令牌列为缺陷,与硬编码色值同级。
- 验证:改一个按钮悬停的组件令牌,跑视觉回归。失败的快照里若出现卡片、输入、导航,就是有外组件在读它。再搜全库:业务路径上出现
button.、input.、dialog.且文件并不属于该组件,每一处都是一次私有性破坏。零命中且回归只动按钮,私有性才成立。