设计 Token 命名的核心不是“看起来整齐”，而是让名称在设计、代码、主题和组件之间稳定表达同一意图。推荐采用基础、语义、组件三级模型，并用“范围—属性—角色—状态—变体”的顺序组合名称。
本文聚焦 Design Token 命名规范，不重复讲完整的变量系统搭建。需要先理解变量类型、模式和作用域时，可阅读 Pixso 变量设计系统指南。
Design Token 命名要解决什么问题？
好名称要同时满足可理解、可扩展、可搜索和可映射。设计师看到 color.text.primary 能理解用途，开发者能找到相同语义，主题切换时只替换引用值，新增状态时也不用推翻整套结构。
- 不要写具体值：
blue-565dff难以承载主题变化。 - 不要写临时页面：
home-card-gray很快会失去上下文。 - 不要混用层级：基础色、语义色和组件专用值应能从名称识别。
- 不要依赖中文缩写：跨设计与代码协作时，使用稳定英文词表更易映射。
基础、语义和组件三级 Token 怎么分？
基础 Token 记录可用值，语义 Token 表达用途，组件 Token 处理组件局部差异。页面和组件优先引用语义或组件 Token，不应直接绑定大量基础值。
| 层级 | 示例 | 适用范围 |
|---|---|---|
| 基础 Primitive | color.blue.600 | 调色板、字号、间距等原始刻度 |
| 语义 Semantic | color.text.primary | 跨组件共享的用途与主题 |
| 组件 Component | button.bg.primary.hover | 确有局部差异的组件状态 |
组件 Token 不宜无限增长。只有当组件无法直接复用语义 Token，且差异需要独立演进时才新增，否则会形成另一套难以维护的别名层。
Design Token 命名语法怎么定？
推荐按“范围—属性—角色—状态—变体”从稳定到具体排列，并允许按类型省略不需要的段。例如 color.bg.brand.hover、border.radius.card.medium、space.component.button.inline。
- 分隔符：团队统一使用点号、斜杠或短横线之一；Pixso 分组可用斜杠，代码导出时再转换。
- 词性：角色使用名词，如
text、surface；状态使用统一词表，如hover、disabled。 - 顺序：不要在不同 Token 中交换
primary与hover的位置。 - 编号：基础刻度可用 50–900 或 1–12；语义层不使用难懂的纯编号。
颜色、间距、字体和圆角如何分别命名？
不同类型共享总体语法，但角色词表应独立维护。颜色关心前景、背景、边框和反馈状态；间距关心布局范围与方向；字体要同时表达字号、行高、字重；圆角则区分容器、控件和全圆形。
| 类型 | 推荐示例 | 避免示例 |
|---|---|---|
| 颜色 | color.text.danger | red-text |
| 间距 | space.layout.section | gap-big |
| 字体 | font.body.medium | text-16-bold |
| 圆角 | radius.control.medium | radius-8 |
如何把 Pixso 变量映射到前端代码？
设计侧保留语义分组，导出层负责把分隔符转换为代码约定。例如 Pixso 中的 color/text/primary 可以映射为 CSS 变量 --color-text-primary，而不必让设计师直接维护代码语法。
:root {
--color-text-primary: var(--color-gray-900);
--color-bg-brand: var(--color-blue-600);
--space-control-inline: var(--space-12);
}
[data-theme="dark"] {
--color-text-primary: var(--color-gray-50);
}W3C Design Tokens Community Group 格式规范 定义了 Token、分组、类型、描述和别名等交换概念，可作为跨工具数据结构参考；它是社区组报告，不应表述为正式 W3C 标准。团队仍要定义自己的命名词表与发布流程。
旧变量如何迁移到新命名规范？
不要一次性全量重命名，先建立映射表和弃用期。按使用量筛出核心变量，确认旧名到新名是一对一还是多对一，再分组件族替换。每批迁移都要检查主题、实例、原型和代码引用。
- 导出旧变量清单，标记类型、当前值、引用次数和负责人。
- 建立旧名、新名、别名和弃用日期四列映射表。
- 从一个页面与组件族开始迁移，保留回滚版本。
- 在设计与代码仓库分别搜索旧名残留。
- 经过一个发布周期后再删除弃用 Token。
在 Pixso 中如何管理 Token 命名？
先按产品或品牌划定变量集合，再用分组表达层级，用模式承载主题或品牌差异。Pixso 变量 支持颜色、数字、文本和布尔类型，数字变量可用于宽高、间距、圆角等属性。
团队还应在 Pixso 设计系统 中记录词表、示例、负责人和弃用策略。变量名称回答“是什么”，文档则解释“何时用、何时不用”。进入工程交付时，再通过 D2C 与组件映射 检查 Token 是否被代码侧正确引用。
Design Token 命名常见问题
Token 名称应该用中文还是英文？
跨设计与代码协作通常使用英文更便于映射；说明文字可以中文。关键是维护受控词表，避免同义词混用。
颜色 Token 能直接叫 blue-500 吗？
基础层可以，页面和组件则应优先引用 color.text.primary 等语义名称，以支持主题和品牌变化。
所有组件都需要组件级 Token 吗？
不需要。多数属性可直接复用语义 Token，只有需要独立演进的局部差异才增加组件 Token。
命名规范多久复审一次？
建议随设计系统版本复审，并在新增大量组件、增加主题或品牌、接入新技术栈时专项检查。
