R1.09.1component token设计

组件级令牌只服务单一组件,不对外复用

别名: 组件令牌 · 私有令牌 · private component tokens

概念解释

button.bg.hover 描述的是按钮这块解剖上、悬停这一态的背景。它不是「一种稍深的表面色」,尽管此刻它的值可能碰巧和某张卡片的悬停色相同。组件令牌(component token)的读者只有这一个组件的实现;卡片、输入、导航去读它,就是在偷用别人的骨头。跨组件要共享的值,走语义别名或更下面的原始值,不走组件令牌。组件令牌对外复用,下一次只改按钮,卡片会跟着变——爆炸半径被悄悄放大到「所有曾经图省事的调用」。

机制

组件令牌编码的是解剖位置:哪个零件、哪种态。解剖是组件私有的,零件名字在别的组件里并不存在或并不同位。读取它的外组件等于声明「我的这块等于按钮的那块」。按钮一旦改自己的悬停(对比度、品牌、按压分离),所有声明过等同的表面一起改,其中多数从未同意过这次改动。共享应当发生在「角色」上:成功背景、危险描边、悬浮层——这些名字不属于任何一个组件。组件令牌的私有性把一次组件改动的爆炸半径钉死在该组件内部。打破私有性,爆炸半径变成「谁图方便引用过」,而这份引用清单通常没有人维护。图方便的动机很强:值看起来一样,少声明一个名字。一样是此刻的快照,不是契约。

边界

同一组件的子零件之间共享组件令牌是合法的:按钮的标签和按钮的图标都读 button.fg.default,仍在一个爆炸半径里。跨产品复制同一组件实现时,令牌文件可以随组件走,那是在分发这个组件,不是外组件在引用。主题切换若被做成「重写 button.」,外组件读 button. 会把主题泄漏成按钮主题;主题应改语义别名。文档示例若把组件令牌写成可复制的公共色板,读者会当公共 API 用——示例必须标明私有。原子色板(原始值)本来就是给许多组件读的,不在这条禁令里;禁的是把带解剖名字的那一层当成色板。

怎么落地

  • 组件令牌放进该组件的私有文件或私有命名空间,构建时不导出给业务仓库。业务代码引用 button.* 应编译失败。
  • 发现两处「值碰巧相同」,在语义别名层补一个角色名,让两处都改读角色,而不是让卡片改读按钮。
  • 代码评审把跨文件引用组件令牌列为缺陷,与硬编码色值同级。
  • 验证:改一个按钮悬停的组件令牌,跑视觉回归。失败的快照里若出现卡片、输入、导航,就是有外组件在读它。再搜全库:业务路径上出现 button.input.dialog. 且文件并不属于该组件,每一处都是一次私有性破坏。零命中且回归只动按钮,私有性才成立。

延伸

  • 同组R1.09.2 令牌命名按角色与状态拼读,不按外观描述 · R1.09.3 层级过深会让取值来源难以追溯 · R1.09.4 尺度类令牌成阶取值,避免任意数值破坏节奏
  • 相邻R1.01 设计令牌 · R1.15 多品牌与多主题
  • 站内检索component token · private tokens · semantic alias

同组卡片

快捷操作

分享

分享当前页面

ios_share

https://hci.top/zh/handbook/R1.09.1