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。

json
{
  "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 在存续期间保持稳定;删除后重建,即使显示名一样,也必须重新审核映射,不能悄悄按名称认作原对象。

Figma 变量映射到稳定令牌路径及跨端名称的数据流

在发布前拦截破坏性更名

发布脚本或人工评审至少检查四件事:

  1. 路径唯一:忽略大小写后不得重名,也不能出现两个路径导出成同一标识。例如 color.action-primary.background 与 color.action.primary-background 都可能生成 --color-action-primary-background,Web 构建必须报冲突。
  2. 引用可解析:每个别名的目标存在、类型相容,不存在 A 引 B、B 又引 A 的循环。
  3. 标识未漂移:对比上次发布的“Figma key → 契约路径”;仅修改 Figma 显示名允许通过,删除重建或改契约路径必须提交迁移说明。
  4. 调用方可迁移:确需把 color.action.primary.background 更名为 color.action.brand.background 时,先发布新键,并让旧键临时别名到新键;例如约定保留两个正式版本,再依据调用方搜索结果决定移除日期。

验收可用三个可复查结果:修改色值不改变调用名;改 Figma 显示名不改变导出名;制造一次导出名冲突会阻止发布。任一检查失败就停止发布,先修正映射或提供兼容别名,不要求所有应用同时改名。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为令牌路径制定稳定命名规则

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通