设计令牌格式模块 2025.10

本格式定义的所有属性均以美元符号（$）为前缀。本规范后续的新属性也会使用该约定。因此，令牌和分组名不得以$字符开头。

此外，由于令牌别名中使用的语法，令牌和分组名称中不得包含以下字符：

• {（左花括号）
• }（右花括号）
• .（点号）

可以通过可选的 $description 属性添加关于令牌用途的纯文本说明。工具可以以多种方式使用描述信息。

例如：

• 风格指南生成工具可以将描述文本与令牌视觉预览一起展示
• IDE可以在自动补全时将描述作为提示气泡显示（类似 API 文档）
• 设计工具可以将描述作为令牌的提示或标签在可选令牌的地方显示
• 转换工具可以将描述渲染为导出变量或常量旁的源代码注释

$description属性的值必须是纯 JSON 字符串，例如：

设计令牌总有明确类型，以便工具可靠地解释其值。

可通过可选的 $type 属性指定令牌类型。如果未在令牌上设置 $type 属性，则其类型必须按如下规则确定：

• 若令牌值是一个引用，则类型为被引用令牌的解析类型。
• 否则，若父分组有 $type 属性，则类型取最近的父分组的 $type 属性。
• 否则，若所有父分组都没有 $type 属性，则无法确定类型，此令牌必须视为无效。

工具不得通过检查值内容来猜测类型。

$type 属性可在不同层级设置：

• 分组级
• 令牌级

$type 属性必须为纯 JSON 字符串，其值须为本规范类型定义中指定的值之一。该值区分大小写。

例如：

可选的 $extensions 属性为对象，工具可以在此为设计令牌添加专有的、用户、团队或厂商相关数据。每个工具必须使用带厂商标识的键，其值可以是任意合法 JSON 数据。

• 键名应选择避免与其它厂商数据冲突，推荐采用反向域名标识法。
• 处理设计令牌文件的工具必须保留所有自己不识别的扩展数据。例如，含有 A 工具扩展数据的令牌文件在 B 工具中打开并保存后，仍必须保留原始的 A 工具扩展数据。

为保持不同支持该格式工具间的互操作性，团队与工具应将扩展数据仅用于非核心的可选元数据，不应包含理解令牌值所必需的信息。

鼓励工具厂商尽量公开扩展数据的规范，方便其他工具兼容，将热门扩展纳入将来的标准特性。

$deprecated 属性可以用于标记某令牌为已弃用，并可选解释原因。弃用原因包括但不限于：

• 设计系统未来会移除此令牌
• 立即移除可能会破坏现有支持
• 不建议今后使用此令牌

工具开发者可以对说明字符串（如包含别名）进行增强。例如，解析该令牌，并在 UI 中链接到文档、代码或可视化替代令牌。例如，“建议改用 {button.activeBorder}” 可作为 JS 输出：

或

分组 MAY 可以包含可选的 $deprecated 属性以将整个分组标记为已弃用。这会扩展到该分组内的所有子令牌，除非被显式覆盖。

分组 MAY 可以包含可选的 $extensions 属性，工具 MAY 可以在其中添加专有的、用户、团队或厂商特定的数据。每个工具 MUST 必须使用带厂商标识的键，其值 MAY 可以是任意合法的 JSON 数据。

$extends 属性在语义上等同于 JSON Schema 的 $ref 关键字（如 [json-schema-2020-12] 所述）及其后续版本。以下两个分组定义在功能上是相同的：

使用 $extends（设计令牌语法）：

{
  "button-primary": {
    "$extends": "{button}",
    "background": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.8, 0, 0.4],
        "hex": "#cc0066"
      }
    },
    "focus": {
      "$value": {
        "colorSpace": "srgb",
        "components": [1, 0.2, 0.6],
        "hex": "#ff3399"
      }
    }
  }
}

使用 $ref（JSON Schema 语法）：

{
  "button-primary": {
    "$ref": "#/button",
    "background": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.8, 0, 0.4],
        "hex": "#cc0066"
      }
    },
    "focus": {
      "$value": {
        "colorSpace": "srgb",
        "components": [1, 0.2, 0.6],
        "hex": "#ff3399"
      }
    }
  }
}

扩展解析遵循简单的处理流程：

1. 查找目标：解析 $extends 引用以定位目标分组
2. 复制继承内容：以目标分组的所有令牌和属性为起点
3. 应用本地覆盖：在相同路径处用本地定义替换任何继承的令牌/属性
4. 添加新内容：包含任何本地存在但继承组中不存在的令牌/属性

以上规则会创建一个已解析的新分组，按照覆盖规则合并继承和本地内容。

分组扩展遵循 深度合并 行为，本地属性会在相同路径下覆盖继承属性：

1. 继承：继承所引用分组的所有令牌和属性（不允许循环引用）
2. 覆盖：本地令牌和属性替换具有相同路径的继承项
3. 新增：具有新路径的本地令牌和属性与继承项并存

覆盖规则：

• 相同路径 = 覆盖：如果继承分组和本地分组在相同路径定义了令牌，则以本地定义为准
• 不同路径 = 合并：不同路径的令牌在最终结果中并存
• 整体替换：在覆盖时，整个令牌定义会被替换（而不是逐属性合并）

input-amount 的结果：

多级覆盖示例：

extended 的结果：

分组 MUST NOT 不得创建循环继承链。以下模式是 无效的：

有效的继承模式：

$extends 支持与 设计令牌别名 相同的引用格式。

$extends 的错误处理遵循 JSON Schema $ref 的错误模式：

• 无法解析的引用：找不到目标分组时
• 无效的目标：引用指向的不是分组（例如指向一个令牌）时
• 循环引用：扩展链产生循环时
• 约束违规：本地属性违反继承约束时

工具 MUST 必须实现与 JSON Schema 验证器用于 $ref 解析相同的错误检测和报告模式。

实现设计令牌解析的工具 MAY 可以选择：

1. 转换为 $ref：将 $extends 转换为标准 JSON Schema $ref 语法，并使用现有 JSON Schema 库进行验证
2. 原生实现：直接实现 $extends，使用与 JSON Schema $ref 处理相同的算法
3. 混合方法：在保持设计令牌特定引用语法的同时，使用 JSON Schema 库进行验证

无论采用何种实现方式，语义行为 MUST 必须与 JSON Schema 2020-12 或更高版本中指定的 $ref 等价。

本规范将 $extends 定义为 JSON Schema 的 $ref 关键字的语法糖，提供了设计令牌特定的引用语法，同时保持等价行为。上述深度合并语义与 JSON Schema 2020-12 在处理带有同级属性的 $ref 时的行为一致。

对于熟悉 JSON Schema 的实现者，$extends 的行为等同于：

• 将 "$extends": "{group}" 转换为 "$ref": "#/group"
• 应用 JSON Schema 2020-12 中对 $ref 的解析并评估同级属性

实现本规范的工具 MAY 可以选择：

1. 转换方法：将 $extends 转换为 $ref 并使用 JSON Schema 库
2. 直接实现：实现上文描述的深度合并行为
3. 混合方法：在保持设计令牌语法的同时使用 JSON Schema 进行验证

无论采用何种实现方法，面向用户的行为 MUST 必须与本规范描述的深度合并语义相匹配。

工具 MUST 必须支持按 [rfc6901] 定义的 JSON Pointer 引用，使用 $ref 属性：

处理分组时，工具 MUST 必须遵循下列解析顺序：

1. 本地令牌 - 具有 $value 属性的直接子项
2. 根令牌 - 名为 $root 的令牌
3. 继承令牌 - 通过 $extends 继承的令牌（若未被覆盖）
4. 嵌套分组 - 递归处理

令牌路径通过用句点 (.) 连接分组名和令牌名来构造。保留令牌名 $root 包含在路径中以保持引用的明确无歧义。

示例：

类型解析按以下优先级规则进行：

1. 令牌显式的 $type 属性（最高优先级）
2. 已解析分组的 $type 属性（在扩展解析之后）
3. 父分组的 $type 属性（向上遍历层级）
4. 若无法确定类型，则令牌无效

带扩展的类型解析： 由于 $extends 遵循 JSON Schema $ref 语义，类型继承行为由约束验证决定，而不是显式的合并规则。本地类型约束会与继承的约束一起根据 JSON Schema 的验证模式进行评估。

在此示例中，分组 extended 必须同时满足其本地的 $type: "dimension" 约束以及来自所引用 base 分组的任何适用约束，遵循 JSON Schema 的约束解析规则。

工具 MUST 必须检测并对以下类型的循环引用抛出错误：

• 令牌别名中的循环引用（见 引用）
• 分组扩展中的循环引用（$extends 引用）
• JSON Pointer 引用中的循环引用（若支持 $ref）

对于 $extends 的循环引用检测遵循与 JSON Schema $ref 相同的要求。工具 SHOULD 应当实现与 JSON Schema 验证器相同的环检测算法。

工具 MUST 必须将此作为影响分组 a、b 和 c 的错误进行报告。

解析后的令牌：

• {input-amount.field.width} → { "value": 100, "unit": "px" } （已覆盖）
• {input-amount.field.background} → #ffffff （从 input 继承）

这演示了组件扩展基础组件但覆盖特定令牌同时继承其他令牌的关键用例。

该结构创建的可访问令牌如下：

分组允许令牌文件作者更好地组织其令牌文件。相关令牌可以嵌套到分组中以符合团队的命名约定或心智模型。在手动编写文件时，使用分组也比使用重复前缀的平铺令牌列表更简洁。

例如：

……相比下面这种平铺结构，可能更方便输入且更易阅读：

允许用户通过 GUI 选择或编辑令牌的工具 MAY 可以使用分组结构以适当的方式呈现逐步披露（例如可折叠的树状视图）。

令牌名称在同一文件中不保证唯一。相同名称可以在不同分组中使用。此外，转换工具 MAY 可能需要以可唯一识别的方式导出设计令牌，例如在代码中作为变量。因此，转换工具 SHOULD 应当使用设计令牌的路径，因为路径在文件内是唯一的。

例如，像 转换工具（如 Style Dictionary）可能会使用如下的设计令牌文件：

……并通过拼接路径创建变量名，将其输出为 Sass 变量，如下所示：

花括号语法专用于引用完整的令牌值，并且总是解析为目标令牌的 $value 属性。

在此示例中，{colors.blue} 解析为完整的颜色对象 {"colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc"}。

重要说明：花括号引用只能目标为完整令牌（具有 $value 属性的对象），不能用于访问令牌值内的单个属性或文档中的任意位置。

对于需要访问令牌值内特定属性或文档结构其他部分的高级用例，令牌必须支持由 [rfc6901] 定义的 JSON Pointer 表示法，使用 $ref 属性。实现本规范的工具必须支持 JSON Pointer 语法。

在此示例中：

• "$ref": "#/colors/blue/$value" 等价于 "{colors.blue}"
• "$ref": "#/colors/blue/$value/components/0" 访问蓝色的红色分量（索引 0）

主要差异：

针对花括号引用：

1. 解析引用：从 {group.token} 中提取令牌路径
2. 拆分路径：转换为段数组 ["group", "token"]
3. 定位令牌：查找目标令牌对象
4. 验证令牌：确保目标具有 $value 属性
5. 返回令牌值：提取并返回 $value 的内容
6. 检查循环：维护解析引用的调用栈以检测循环

针对 JSON Pointer 引用：

1. 解析 JSON Pointer：从 #/path/to/target 中提取路径段
2. 遍历文档：逐段导航文档结构
3. 应用 JSON Pointer 规则：
   • 数组上下文中的数字段被视为数组索引
   • 对象上下文中的所有段被视为属性名
   • 处理转义字符（~0, ~1）
4. 验证目标：确保最终目标存在且可访问
5. 返回值：提取并返回解析出的值

别名可以引用其他别名。在此情况下，工具必须沿着引用链逐一解析，直到找到具有显式值的令牌为止。

在此示例中，{semantic.link} 通过链式跟随解析：semantic.link → semantic.brand → base.primary，最终解析为与 {base.primary} 相同的颜色值。

引用不得形成循环。如果设计令牌文件包含循环引用，则该循环链中所有令牌的值均为未知，工具应当向用户显示适当的错误或警告信息。

工具必须检测并将其报告为影响该循环链中所有令牌的错误。

在此示例中：

• layout.small 使用与 base.spacing 相同的数值（16），但使用不同的单位（rem）
• layout.large 使用与 base.spacing 相同的单位（px），但数值不同（32）

在此示例中：

• 两个标题都继承了 base.text 的 fontFamily 与 lineHeight
• 每个标题都定义了自己的 fontSize 与 fontWeight
• 对基础字体族或行高的更改会自动影响所有标题

• 根引用： #/（指向文档根）
• 对象属性： 使用 / 分隔每一级（例如 #/group/token/$value）
• 数组索引： 数组元素使用数字索引（例如 #/color/$value/components/0）
• 特殊字符： 必须根据 JSON Pointer 规则进行转义：
  • ~ 变为 ~0
  • / 变为 ~1

由于设计令牌将其值存储在 $value 属性中，指向令牌值的 JSON Pointer 路径遵循可预测的模式：

1. 解析 JSON Pointer：从 #/path/to/target 中提取路径段
2. 遍历文档：逐段导航
3. 应用 JSON Pointer 规则：
   • 数组上下文中的数字段转为数组索引
   • 对象上下文中的段视为属性名
   • 处理转义字符（~0, ~1）
4. 验证目标：确保最终目标存在且可访问
5. 返回值：提取并返回解析出的值

1. 解析引用：从 {group.token} 中提取令牌路径
2. 拆分路径：转换为段数组 ["group", "token"]
3. 定位令牌：查找目标令牌对象
4. 验证令牌：确保目标具有 $value 属性
5. 返回令牌值：提取并返回 $value 的内容
6. 检查循环：维护解析引用的调用栈以检测循环

工具必须对以下情况报告错误：

• 语法无效：花括号或 JSON Pointer 语法格式错误
• 路径不可解析：目标路径在文档中不存在
• 无效的令牌引用：花括号语法引用了非令牌对象
• 循环引用：引用链回到自身
• 类型不匹配：被引用的值与期望类型不兼容

实现设计令牌解析的工具必须：

1. 支持花括号语法，作为令牌到令牌引用的主要引用机制
2. 支持 JSON Pointer 语法，用于文档级引用和属性访问
3. 验证引用目标，确保其指向有效的令牌（对花括号）或有效的文档位置（对 JSON Pointer）
4. 按照本规范定义的解析算法解析引用（参见 解析算法）
5. 在尝试解析之前检测循环引用
6. 在内存/存储中保留引用，并仅在需要值时才解析
7. 将被引用令牌的更改传播到所有别名

清晰解析：

工具必须对以下情况报告错误：

• 引用语法无效：花括号或 JSON Pointer 语法格式错误
• 引用不可解析：目标路径不存在
• 循环引用：引用链回到自身
• 类型不匹配：被引用的属性类型与令牌类型不兼容
• 无效的属性路径：尝试引用不存在的属性

• $value.unit 仅可为 "px" 或 "rem"。
  • px：表示视口上的理想化像素。在 Android 上等价于 dp，在 iOS 上等价于 pt。因此，转换工具 SHOULD（应当）将其转换为这些或其他等效单位（如有需要）。
  • rem：表示系统默认字体大小的倍数（该默认大小 MAY 可由用户配置）。1rem 等于默认字体大小的 100%。在 Android 上 1rem 等价于 16sp。并非所有平台都有 rem 的等价物，因此转换工具 MAY（可能）需要在此类平台上通过假定一个默认字体大小（通常为 16px）将其有损转换为固定像素大小。
• 即使 $value.value 为 0，也必须提供 $value.unit。

• $value.unit 仅可为 "ms" 或 "s"

字符串形式的描边样式值 MUST 必须设置为下列预定义值之一：

• solid
• dashed
• dotted
• double
• groove
• ridge
• outset
• inset

这些值与 CSS 中等价的 “line style” 值 含义相同。根据 CSS 规范，它们的确切渲染是实现相关的。例如，dashed 样式中虚线与空白的长度在不同工具之间可能有所差异。

对象形式的描边样式值 MUST 必须包含以下属性：

• dashArray：一个由 dimension 值 和/或对 dimension 令牌的引用组成的数组，用以指定交替虚线与间隙的长度。数组中的每个元素必须是显式的 dimension 值或对 dimension 令牌的引用。如果提供的是奇数个值，则会重复该值列表以得到偶数个值。
• lineCap：下列预定义字符串值之一："round"、"butt" 或 "square"。这些值与 SVG 中 stroke-linecap 属性的含义相同。

字符串值和对象值是表达描边样式的两种互斥方式。例如，一些字符串值（如 inset 或 groove）无法仅通过 dashArray 和 lineCap 来表达，因为它们需要实现相关的方式对边框或轮廓的某些部分进行加亮或变暗。反之，精确定义的 dashArray 与 lineCap 子值组合未必能产生与 dashed 或 dotted 关键字相同的视觉效果，因为这些也依赖于实现细节。

此外，某些工具与平台可能不支持本类型表示的全部描边样式。当在显示或导出不被其原生支持的 strokeStyle 令牌时，它们应回退到其支持的最接近近似效果。

如何选择“最接近的近似”属于实现细节。不过，下列示例说明工具在某些场景中MAY（可以）使用的回退方案。