UI 视觉设计 / 系统课时
为令牌路径制定稳定命名规则
为令牌路径制定稳定命名规则
设计师调整变量分组、按钮颜色或主题模式时,不应迫使各端批量改调用名称。本篇约定一套独立于 Figma 显示名和平台语法的令牌路径,并用主按钮背景色走通命名、别名、映射与变更验收。
学习目标
- 用统一层级区分原始色、语义用途与组件专用令牌。
- 把 Figma 变量映射到稳定、平台无关的契约键。
- 检查更名兼容性、别名引用和跨平台导出冲突。
先固定路径语法
团队约定稳定键采用 类别.领域.角色.属性,按需要保留 3~5 段;这是项目规范,不是 Figma 或 DTCG 强制的分类。每段优先使用小写英文、数字和短横线,色阶末段允许纯数字。禁止中文、空格、平台前缀及无意义缩写。
| 层级 | 稳定键示例 | 表达的含义 |
|---|---|---|
| 原始值 | color.palette.blue.600 |
蓝色色阶,不绑定具体控件 |
| 语义用途 | color.action.primary.background |
主要操作的背景色 |
| 组件特例 | color.component.dialog.backdrop |
仅弹层遮罩使用的颜色 |
语义路径应该回答“用在哪里”,而不是“现在是什么颜色”。主要操作从蓝色切到紫色时,应让语义令牌改为引用 color.palette.purple.600,而不是给 color.palette.blue.600 填入紫色;color.action.primary.background 仍保持不变。同一用途不同时保留 bg 和 background 两套正式命名。
采用 DTCG 2025.10 格式时,单个组名或令牌名不得包含 .、{、},也不能以 $ 开头;这里的点号仅用于表示多级路径,不能直接写进单个 JSON 属性名。
用原始值和别名验证命名
以下 tokens.json 是完整的 DTCG 2025.10 令牌文件示例。color.action.primary.background 不复制色值,而是引用原始色 color.palette.blue.600。
{
"color": {
"palette": {
"blue": {
"600": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0.145, 0.388, 0.922],
"alpha": 1
}
}
}
},
"action": {
"primary": {
"background": {
"$type": "color",
"$value": "{color.palette.blue.600}",
"$description": "主要操作的默认背景色"
}
}
}
}
}文件可以直接通过 JSON 解析;花括号引用还需要支持 DTCG 2025.10 的令牌处理器解析。验证时确认引用目标存在、类型均为 color,两条路径解析为相同颜色(约 #2563EB)。把原始色改为 #1D4ED8 对应的颜色值后,语义令牌应跟随变化,但语义路径不能改变。
把设计侧显示名与稳定键分开
在 Figma Design 中点击画布空白处,使用右侧 Local variables → Open variables 进入变量面板。将示例放入 Semantic Colors 集合,并命名为 color/action/primary/background;斜杠便于变量分组,但不应直接把完整显示名当作不可变 API。导出层保存“Figma 变量 key → 契约路径”的显式映射,修改显示名时仍找到同一变量。
| 位置 | 本例的标识 |
|---|---|
| Figma 显示名 | color/action/primary/background |
| 稳定契约路径 | color.action.primary.background |
| Web 导出名 | --color-action-primary-background |
| iOS 导出名 | colorActionPrimaryBackground |
| Android 导出名 | color_action_primary_background |
后三个名称是团队规定的生成结果,不是 Figma 自动提供的固定命名。根据 Figma Variables API,变量的 key 在存续期间保持稳定;删除后重建,即使显示名一样,也必须重新审核映射,不能悄悄按名称认作原对象。

在发布前拦截破坏性更名
发布脚本或人工评审至少检查四件事:
- 路径唯一:忽略大小写后不得重名,也不能出现两个路径导出成同一标识。例如
color.action-primary.background与color.action.primary-background都可能生成--color-action-primary-background,Web 构建必须报冲突。 - 引用可解析:每个别名的目标存在、类型相容,不存在 A 引 B、B 又引 A 的循环。
- 标识未漂移:对比上次发布的“Figma key → 契约路径”;仅修改 Figma 显示名允许通过,删除重建或改契约路径必须提交迁移说明。
- 调用方可迁移:确需把
color.action.primary.background更名为color.action.brand.background时,先发布新键,并让旧键临时别名到新键;例如约定保留两个正式版本,再依据调用方搜索结果决定移除日期。
验收可用三个可复查结果:修改色值不改变调用名;改 Figma 显示名不改变导出名;制造一次导出名冲突会阻止发布。任一检查失败就停止发布,先修正映射或提供兼容别名,不要求所有应用同时改名。