Design Tokens 工程化实践

Design Tokens 经常被误解为"把颜色值抽成变量"。

更准确的定义是：Design Tokens 是设计决策的结构化表达，它让"设计意图"变成可编程、可复用、可跨平台分发的数据。

一个成熟的 Design Tokens 体系需要回答：

如何分层（语义 vs 原始值）
如何命名（人类可读 + 工具可解析）
如何输出（CSS/SCSS/JS/iOS/Android）
如何管理版本与变更
如何保证设计与代码一致

这篇文章按"你要在生产上长期维护一个设计系统"为目标，给出：

可复制的分层模型与命名规范
工具链选型与输出管线
CI/CD 集成与版本管理
变更流程与质量门禁

1. 先统一语言：Design Tokens 的三层模型

1.1 三层结构

最佳实践是把 Tokens 分为三层：

层级	含义	示例
Primitive（原始层）	原始值，无语义	`blue-500: #3b82f6`
Semantic（语义层）	抽象语义	`color-primary: {blue-500}`
Component（组件层）	组件专用	`button-bg: {color-primary}`

1.2 为什么要分层？

原始层保证视觉一致性（所有蓝色都来自统一色板）
语义层让意图明确（primary 可以改底层值，但语义不变）
组件层让组件可复用（button 的背景色随主题变，但组件结构不变）

分层的核心收益是：你可以在任意层做调整，而不破坏上层依赖。

2. 命名规范：人类可读 + 工具可解析

一个好的命名体系应该：

自解释（看名字知道用途）
一致性（同类 token 遵循相同模式）
可扩展（新增 token 不破坏现有规则）

2.1 推荐的命名模式

{category}-{property}-{variant}-{state}

示例：

color-text-primary
color-bg-secondary-hover
spacing-padding-lg
typography-heading-h1-font-size

2.2 避免"魔法值"与缩写

反例：

clr1（不知道是什么颜色）
spc8（不知道是 8px 还是 8rem）

正例：

color-primary
spacing-md

3. 数据格式：JSON 是最佳选择

推荐用 JSON（或 YAML）存储 Tokens：

{
  "color": {
    "primitive": {
      "blue": {
        "500": { "value": "#3b82f6" }
      }
    },
    "semantic": {
      "primary": { "value": "{color.primitive.blue.500}" }
    }
  }
}

优势：

工具友好（可被 Style Dictionary/Theo 等解析）
人类可读
支持引用（semantic 层引用 primitive 层）

4. 工具链：Style Dictionary 是事实标准

Style Dictionary 是 Amazon 开源的 Tokens 转换工具。

它的核心能力：

读取 JSON Tokens
输出多平台格式（CSS/SCSS/JS/iOS/Android）
支持自定义转换与模板

4.1 基础用法

// config.json
{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "dist/css/",
      "files": [{
        "destination": "variables.css",
        "format": "css/variables"
      }]
    },
    "js": {
      "transformGroup": "js",
      "buildPath": "dist/js/",
      "files": [{
        "destination": "tokens.js",
        "format": "javascript/es6"
      }]
    }
  }
}

运行：

style-dictionary build

输出：

dist/css/variables.css（CSS 变量）
dist/js/tokens.js（JS 对象）

5. Figma 集成：设计即代码的起点

在真实工作流里，Tokens 通常从 Figma 开始。

5.1 Figma Tokens 插件

推荐使用 Figma Tokens 插件：

在 Figma 里定义 Tokens（颜色、字体、间距）
导出为 JSON
同步到 Git

5.2 自动化同步流程

理想工作流：

设计师在 Figma 更新 Tokens
插件自动推送到 Git
CI 触发 Style Dictionary 构建
产物自动发布到 npm/CDN
开发者拉取新版本

关键点：设计变更 → 代码变更的全流程自动化。

6. 多平台输出：一份数据，多端复用

Design Tokens 的强大之处在于：一份定义，多端输出。

6.1 Web 端

输出格式：

CSS 变量（--color-primary）
SCSS 变量（$color-primary）
JS 对象（tokens.color.primary）

6.2 移动端

输出格式：

iOS：Swift 常量 / UIKit Color
Android：colors.xml / dimens.xml

6.3 设计工具

输出格式：

Sketch：JSON 导入
Figma：同步插件

7. 版本管理：Tokens 也要语义化版本

Design Tokens 是"依赖"，必须做版本管理。

7.1 发布策略

建议用 npm 发布 Tokens：

npm publish @your-org/design-tokens

版本规则：

MAJOR：破坏性变更（删除 token、重命名）
MINOR：新增 token
PATCH：修正值（例如颜色微调）

7.2 变更日志（Changelog）

每次发布都应记录：

新增了哪些 tokens
修改了哪些值
删除/废弃了哪些 tokens

这让下游开发者能快速评估影响。

8. CI/CD 集成：让 Tokens 变更可追溯

建议在 CI 里做这些事：

8.1 自动构建与发布

# .github/workflows/tokens.yml
name: Build and Publish Tokens
on:
  push:
    branches: [main]
    paths:
      - 'tokens/**'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: npm run build:tokens  # Style Dictionary
      - run: npm version patch
      - run: npm publish

8.2 变更对比与通知

在 PR 里展示 Tokens 变化：

哪些 token 新增
哪些 token 值变化
影响范围评估

工具：用 diff-json 或自定义脚本。

9. 质量门禁：防止破坏性变更

建议在 CI 里做检查：

9.1 命名规范检查

token 名称是否符合规范
是否有重复定义

9.2 引用完整性检查

semantic 层引用的 primitive 是否存在
是否有循环引用

9.3 变更影响评估

删除 token 是否有下游依赖
值变化是否超过阈值（例如颜色对比度）

10. 一套可复制的工程结构

推荐的目录结构：

design-tokens/
├── tokens/
│   ├── primitive/
│   │   ├── color.json
│   │   ├── spacing.json
│   │   └── typography.json
│   ├── semantic/
│   │   └── theme.json
│   └── component/
│       └── button.json
├── scripts/
│   └── build.js
├── dist/                # 构建产物
│   ├── css/
│   ├── js/
│   └── ios/
├── config.json          # Style Dictionary 配置
└── package.json

11. 上线检查清单

Tokens 是否有清晰的三层结构
命名是否一致且自解释
是否用 Style Dictionary 或类似工具
是否有 Figma 到 Git 的同步流程
是否做了多平台输出（Web/iOS/Android）
是否用 npm 做版本管理
CI 是否有自动构建与发布
是否有变更对比与影响评估

总结

Design Tokens 工程化的核心是：

用结构化数据表达设计意图
用工具链实现"一份定义，多端输出"
用版本管理保证变更可控
用 CI/CD 让设计与代码自动同步

Design Tokens 工程化实践