设计 Token 流水线

搭 CI 流水线把 Figma token 转成 CSS/Tailwind/iOS/Android 格式。

为什么

设计 token 是设计与工程的契约——漂移则每屏漂移。token 流水线让 Figma 成单一事实源，每平台是生成消费者：在 Figma 改颜色，CSS、Tailwind、iOS Swift、Android XML 全在一个 PR 更新。无流水线，每平台维护自己的 token 副本，品牌刷新变 3 周跨团队项目且必然不一致。流水线还强制命名约定（color.brand.primary 非 color.blue）并防非法值（不在 scale 的 13px 字号）。

何时使用

发布到 ≥2 平台或有 ≥20 token 时。搭 Style Dictionary 约 3-4 小时。单平台小应用可跳过。

如何做

1. 用 Tokens Studio 插件在 Figma 定义 token，同步到仓库 tokens.json
   - 结构：{ color, typography, spacing, radius, shadow, motion }
   - 用语义名：color.surface.primary，非 color.white

2. 装 Style Dictionary 写配置输出所有平台
   - CSS：--color-surface-primary
   - Tailwind：extend.colors.surface.primary
   - iOS：UIColor 扩展；Android：colors.xml

3. 加 CI job 在每碰 tokens.json 的 PR 重新生成 token
   - 跑 style-dictionary build，提交输出，输出无源变更而变则失败
   - 这防手改生成文件

4. 加 token linter 强制命名和值约束
   - 所有颜色须在品牌调色板；无一次性 hex 值
   - 字号须在 type scale；无 13px、15px 等

5. token 版本化：破坏性变更（重命名、删除）需主版本 bump
   - 消费者迁移期间可锁版本

示例

// style-dictionary.config.ts
import StyleDictionary from "style-dictionary";

StyleDictionary.extend({
  tokens: ["tokens.json"],
  platforms: {
    css: { transformGroup: "css", buildPath: "src/styles/", files: [{ destination: "tokens.css", format: "css/variables" }] },
    tailwind: { transformGroup: "js", buildPath: "src/tokens/", files: [{ destination: "tailwind.js", format: "javascript/module" }] },
    ios: { transformGroup: "ios-swift", buildPath: "ios/", files: [{ destination: "Tokens.swift", format: "ios-swift/class.swift" }] },
  },
}).buildAllPlatforms();

// CI：.github/workflows/tokens.yml
- run: npx style-dictionary build
- run: git diff --exit-code src/styles/tokens.css  # 手改则失败

常见问题

⚠按值命名 token（color.blue500）而非角色（color.surface.primary），品牌重塑要重命名每 token。
⚠手改生成 CSS 而非源 JSON，下次流水线运行覆盖修复。
⚠不版本化 token，重命名同时破所有消费者无迁移路径。
⚠把非设计值（z-index、动画时长）放 token 系统，变垃圾场。

最佳实践

✓用三层 token 系统：原始（blue-500）→ 语义（color.primary）→ 组件（button.bg）——每层可重映射不碰其他。
✓从 token 生成 TypeScript 类型，token 名拼写错是编译错误。
✓token JSON 放独立包（monorepo），多 app 消费同版本。
✓token linter 跑 pre-commit hook 非仅 CI——推送前抓命名违规。