W3C Design Tokens Community Group 规范深度研究

00摘要：核心论断

只读这一页也能带走结论。每条论断可证伪、有出处，正文各章是其展开。

↑ 目录

01范式判定：它是什么、不是什么

讨论规范之前先钉死概念。围绕 design token 有四组经常被混用的词，DTCG 只标准化了其中最小的一块。

1.1 十年时间轴：从名词到稳定规范

design token 这个词 2014 年诞生于 Salesforce 设计系统团队（Jina Anne 与 Jon Levine），而它拿到第一份稳定规范文本，用了整整十一年。中间的每一次跃迁都值得看清：2017 年 Style Dictionary 开源证明「令牌可以编译成任何平台代码」；2021-2022 两版编辑草案确立了今天 $value/$type 的形状；2025 年的两次合入（现代色彩、组继承）补上了规模化使用的最后两块短板，随后在 2025 年 10 月一次性发布了 Format、Color、Resolver 三个稳定模块。

1.2 概念分野：四个经常被混用的词

2022 年 11 月的 GitHub issue #187 把这个分野正面提了出来：token 的值在全系统不变、是常量；会变的是 theme 引用 token 的键。把两者都叫「design token」制造了大量混淆。2025.10 的模块划分（格式不含 theme、theme 进 Resolver）正是对这场争论的规范化回应。

1.3 判别式：它不是 W3C 标准

这是几乎所有二手报道都会写错的一点，也是写进合同前必须分清的一点。规范文本原文：*「This specification was published by the Design Tokens Community Group. It is not a W3C Standard nor is it on the W3C Standards Track.」*它的法律与流程地位是：

工程上的结论：它没有 W3C Rec 的强制力，但拥有比多数 W3C Rec 更直接的行业背书——Adobe、Google、Microsoft、Meta、Amazon、Figma、Salesforce、Shopify、Sony、Pinterest、NYT、Disney 等 40+ 组织参与，Style Dictionary、Tokens Studio、Terrazzo 提供参考实现。对采用决策而言，「事实标准」比「官方标准」更重要。

↑ 目录

02理论根基：为什么必须是这个形状

规范的每个形状选择都可以推导出具体工程动作。这不是审美偏好，是约束条件下的最优解。

2.1 四个形状选择及其工程推论

2.2 小核心、大外围：规格面积的最小化

Format 模块的规范性内容可以画在一页纸上：一条判定规则、7 种基本类型、4 种组合类型、5 个可选属性。对比同类设计系统规范动辄数百页，这个「规格面积」的差异是刻意的——每一条强制性规定都是未来所有工具必须实现的成本。DTCG 把成本压到最低，把可变的部分（色彩空间、主题策略、厂商元数据）放进独立模块或 $extensions。

这解释了采用速度：一个新工具支持「读 DTCG」的最小实现，只需要一个 JSON 解析器和一条判定规则；支持得好，才需要实现别名解析、类型继承、Resolver。标准用最小的一致性内核换来了最大的一致性收益——所有工具至少 agree on the base（原始 token、色彩、间距、引用语法），只在最年轻的边缘（组合类型）存在方言。

↑ 目录

03规范架构：三个模块，一次发布

2025.10 不是一份文档，是三份同时发布、互相引用的稳定模块。模块边界本身就是设计决策。

3.1 模块职责与边界

这个切分回答了 v1 草案阶段最大的悬案。2019-2021 年间社区反复争论「主题化要不要进格式」：$themes、mode 字段等方案都曾被提出又搁置。最终答案是格式保持纯粹（描述静态数据），主题化作为解析策略独立成模块——两者可以分开演进，工具可以只实现 Format 而不实现 Resolver。

↑ 目录

04Format 模块精读：一页纸的内核

这一章是规范的「精读笔记」，全部内容可在 Format Module 2025.10 原文中逐条对应。

4.1 一条判定规则

含 $value 属性的对象是 token；不含的是 group。对象同时含 $value 与子项属无效结构，工具必须报错。

解析器因此不需要配置、不需要启发式：$value 是保留字，一条规则遍历整棵 JSON 树。token 名称本身有字符限制——不能以 $ 开头、不能含 {、} 或 .（避免与别名语法冲突），且区分大小写。

4.2 Token 解剖

{
  "color": {                          // group：不含 $value 的对象
    "$type": "color",                 // 组级类型：组内未声明的 token 继承
    "$description": "品牌色板",
    "accent": {                       // 嵌套 group
      "$root": {                      // $root 保留名：该组的根 token
        "$value": { "colorSpace": "oklch",
                    "components": [0.65, 0.21, 290],
                    "alpha": 1 },     // Color 模块的对象写法
        "$type": "color",
        "$description": "主品牌色（OKLCH）"
      },
      "primary": {
        "$value": "{color.accent.$root}",   // 别名：完整 token 引用
        "$deprecated": "改用 color.action.primary"
      },
      "fallback": {
        "$value": "#1D4ED8",          // 旧式 hex 写法仍然合法
        "$extensions": {              // 厂商扩展：工具必须原样保留
          "org.example.tool": { "id": "a1b2" }
        }
      }
    }
  }
}

4.3 属性总表

4.4 类型系统：7 基本 + 4 组合

注意：typography 曾出现在规范示例中，但 2025.10 的类型清单未将其列为正式类型——组合类型家族仍在收敛中（见论断 8）。8.8 节也以非规范语气提及 fontStyle、percentage、file 等未来候选。

4.5 文件约定

推荐扩展名 .tokens / .tokens.json；推荐 media type application/design-tokens+json（application/json 亦合法，工具必须两者都支持）。这使 token 文件可以被操作系统、编辑器、CI 识别为一类独立资产，而不是散落的「某种 JSON」。

↑ 目录

05引用与继承：token 系统的价值所在

如果说 $value 是格式的躯体，引用系统就是它的神经系统——语义层指向原始层、组件层指向语义层，改动沿链传播。

5.1 两种引用语法，工具必须都支持

设计意图明确：花括号语法为人类与设计工具而设，JSON Pointer 为程序化访问兜底。规范 7.5.1 要求工具同时支持两者——只实现其一不算合规。引用约束：支持链式引用（alias 套 alias）；循环引用中所有 token 值未知，必须报错；引用目标不存在、解析后类型不匹配也必须报错。

5.2 $extends：组级继承（2025.10 新增）

PR #298 之前，group 只是「带元数据的文件夹」：组不能有默认值、不能复用。2025.10 补上了继承：

{
  "button": {
    "$type": "color",
    "$extends": "{variant-base}",   // 深度合并 variant-base 的全部内容
    "danger": { "$value": "{color.palette.red}" }   // 本地路径覆盖继承值
  }
}

规则：深度合并（deep merge），本地同名路径覆盖继承来源；禁止循环引用；语义等同 JSON Schema 的 $ref。$deprecated 同样沿组向下扩散——组被标记弃用，其下所有子 token 视为弃用，除非子 token 显式写 $deprecated: false 解除。这组机制让「组件级 token 家族」（一个按钮的全部状态色）从重复劳动变成一次定义、处处继承。

↑ 目录

06Color 模块：从 hex 单声道到 CSS Color 4 全频段

hex 是 sRGB 时代的容器。设计工具早已运行在广色域里，旧规范却只允许一种颜色写法——这是 v1 最大的升级。

6.1 新旧两种写法

// 旧式（仍然合法）：hex 字符串，隐含 sRGB
{ "$type": "color", "$value": "#0066CC" }

// 新式：显式色彩空间的对象，CSS Color Module 4 全部空间可用
{ "$type": "color", "$value": {
    "colorSpace": "oklch",
    "components": [0.65, 0.15, 250],
    "alpha": 1
} }

6.2 支持的色彩空间

Color 模块对齐 CSS Color Module 4，覆盖：srgb、srgb-linear、display-p3、a98-rgb、prophoto-rgb、rec2020、xyz、xyz-d50、xyz-d65、hsl、hwb、lab、lch、oklab、oklch。工程含义：

• 设计侧：设计师在 Figma/Penpot 中使用的颜色模型可以原样进出 token 文件，不再被压扁成 hex 再猜回来。
• 代码侧：Style Dictionary、Tokens Studio 等工具在导出时负责向下转换（如 oklch → sRGB hex），支持广色域的平台自动输出 color(display-p3 …)。
• 最佳实践：以 oklch 等感知均匀空间作为创作源（衍生色阶、透明度变体都在均匀空间推导），hex 只是导出产物——「先写 hex」是一条不可逆的路。

↑ 目录

07Resolver 模块：主题化的正解与过渡期的方言

3 个品牌 × 2 种模式 × 4 个平台 = 24 份几乎重复的 token 文件——Resolver 用「一次定义、按需解析」终结这道乘法题。

7.1 关键澄清：两种「主题化方言」为何还存在

一个容易误读的点：Format 模块本身没有 mode/theme 字段。于是 2025 年的过渡生态里存在两种方言——这不是规范的缺陷，而是发布节奏的现实：

选型含义：新项目直接按 Resolver 设计目录结构（base + modifiers）；存量工具链用「按 mode 拆文件」最稳妥——它是社区推荐模式，未来可机械迁移到 Resolver。

↑ 目录

08工具生态与选型

「谁支持、支持到什么程度」决定今天的迁移路径。参考实现与跟随者要分开看。

8.1 支持矩阵（截至 2026-09）

8.2 选型决策树

↑ 目录

09证据全景：采用度数据与反证据

标准的胜利 ≠ 实践的成熟。下面每条数据都标注了来源类型与证据强度，并直接列出与之相悖的证据。

9.1 证据表

9.2 反证据与数据口径注记

• 「84% 采用」是宽口径：它数的是「以某种形式使用 token 的团队」，不等于跑通 DTCG 管线、更不等于端到端治理。引用时必须带上 40% 管线率一起说，否则就是用标题撒谎。
• Figma 的现实不支持「标准已胜利」叙事：变量本身无类型语义（裸 float 无单位），工具读取时只能靠上下文猜；原生导出在 2026 年仍是「宣布中」加插件生态补位。最大的设计源工具恰恰是标准落地最慢的一环。
• 组合类型支持弱于基座：colors/spacing/dimension 可靠赖标准；typography/shadow 等「工具支持仍在追赶」。把组合 token 当标准能力押注的团队，可能要吃方言期成本。
• 调查样本与自报偏差：zeroheight 报告不同题项样本量不一（约 300 / 部分题项 147 名从业者），且全部为自报数据；「稳定/不稳定」的自我评估尤其主观。

↑ 目录

10落地：成熟度阶梯、90 天路线与迁移清单

把标准变成工程动作。先定位自己在阶梯上的位置，再按 90 天节奏推进。

10.1 90 天路线

10.2 迁移清单（存量 token → 2025.10）

1. 结构改造是机械的：每个值包进 $value、补 $type、引用改写为 {path.to.token}。Style Dictionary v4 可直接读 DTCG，多数团队只需改配置 + 一轮 schema 校验，不必手改每个文件。
2. 顺手审计语义层：迁移把每个引用变成显式的、可 lint 的。正是清理「语义 token 并没有真的 alias 到你以为的基础 token」这类历史漂移的最佳时机。
3. 组合类型保持谨慎：colors/spacing 可以完全依赖标准；typography/shadow 先在单一编译工具内闭环，避免跨工具往返。
4. Figma 侧：变量命名用点路径（color.bg.default）以便导出即成组；接受导入类型限制（组合样式留在代码侧或插件层）。
5. 验收标准：一名工程师改一处 token 值 → 跑一次构建 → Web/iOS/Android 三端同时生效，全程无人手改样式表。

↑ 目录

11反模式清单与 AI 新变量

标准解决不了的部分，靠规避反模式解决。每条给出症状与修正。

11.1 反模式

11.2 AI 时代的新变量：token 文件是机器接口

2026 年的一个结构性变化：AI 编码工具与设计 agent 开始把 token 文件当作设计系统的机器可读接口。这改变了两件事的权重：

• Drift 的成本被放大：过去漂移每季度人工清理一次；现在指向陈旧 token 的 agent 会以无人审查的速度批量生成「看起来对、值已过期」的界面——误差复利而不是被等待稀释。
• 校验从建议变成门禁：前置 schema 校验（AJV 等）+ 编译后 lint + 发布前 token 审计脚本（对比上次发布快照，捕捉删除/改名/引用目标变更），这三层门禁是 AI 时代 token 系统的最低配置。

↑ 目录

12结论与参考来源

12.1 结论（这是观点，不是共识）

1. 格式之争已经结束。2025.10 之后还在自造 token 格式，等于在 TCP/IP 之上发明新协议——收益为零、互通成本全自负。基座（原始值、色彩、间距、引用语法）可以立即依赖。
2. 但「标准化」只完成了一半。90% 的采用率与 5% 的双向同步之间的鸿沟是组织和治理问题，任何规范都帮不了；这部分的投资回报目前高于格式本身。
3. Figma 是最大的单点风险与单点机会。它类型语义的缺失让「标准」在设计源一端仍是插件的天下；反过来，一旦其原生导出全面落地，生态将从「收敛中」跳到「收敛完成」。对 Figma 重度团队的务实策略：以 DTCG 文件为真源，把工具当视图。
4. 组合类型按「赌注」管理，原始与语义 token 按「事实」管理——两者的确定等级不同，迁移策略也应不同。
5. 未来 12 个月值得盯的三件事：Figma 原生导出的落地深度；Style Dictionary × Terrazzo 联合格式提案对组合类型的收敛；Resolver 在主要工具中的实现进度（它决定多品牌系统的标准化解法何时可用）。

12.2 参考来源

证据处理说明：所有引用数据已回溯一手来源；行业调查为自报数据（样本与口径见 9.2 节注记）；标注「方向性判断」的条目为基于多个独立来源交叉印证的推断，非硬数据。规范原文引用以英文为准，中文为本文翻译。

↑ 目录