设计 Token 体系搭建从前端变量到跨平台一致性的工程化实践一、设计师在 Figma 里改了一个色值前端要在 37 个文件里改 89 处如果你经历过这个场景你需要一个设计 Token 体系。设计 TokenDesign Token这个概念被提出快十年了但在国内前端团队的落地情况依然不乐观。问题不在于不知道 Token 是什么而在于怎么在工程里把它用起来而不只是一堆 JSON 文件。设计 Token 的本质是将设计决策抽象为平台无关的变量然后通过转译工具生成各平台Web、iOS、Android、Flutter的原生代码。它让设计师在 Figma 改一个主色这件事的工程影响从全局搜索替换变成改一行 JSON自动生成所有平台的代码。这篇文章我会从 Token 的层级设计、命名规范、转译工具链、CI 集成四个维度给你一套可以直接照搬的 Token 体系搭建方案。二、设计 Token 的层级架构为什么需要三层很多人直接把 Figma 里的色值写成 CSS 变量这就跳过了最重要的语义层// 错误基础值和语义值混在一起 { color-primary: #3B82F6, color-primary-hover: #2563EB }这种结构的致命问题是当你想在暗黑模式下把主色从#3B82F6换成#93C5FD时你需要改的是语义 Token而不是基础色值。如果基础和语义混在一起你就失去了一个值关联多个语义的灵活性// 正确三层分离 // primitives.json { blue: { 500: { value: #3B82F6 }, 600: { value: #2563EB }, 300: { value: #93C5FD } } } // semantics.json { color: { primary: { value: {blue.500} }, primary-hover: { value: {blue.600} }, primary-on-dark: { value: {blue.300} } } } // 暗黑模式只需要这一层 // semantics-dark.json { color: { primary: { value: {blue.300} }, primary-hover: { value: {blue.200} } } }三、Token 体系的完整工程实现命名规范使用 CTICategory / Type / Item结构[category]-[type]-[item]-[variant]-[state] 示例 color-background-primary-hover font-size-heading-xl spacing-layout-section-gap radius-component-button shadow-elevation-card完整的 Token Map 示例{ color: { text: { primary: { value: {color.neutral.900} }, secondary: { value: {color.neutral.600} }, disabled: { value: {color.neutral.400} }, inverse: { value: {color.neutral.0} } }, background: { primary: { value: {color.neutral.0} }, secondary: { value: {color.neutral.50} }, overlay: { value: rgba(0, 0, 0, 0.5) } }, border: { default: { value: {color.neutral.200} }, focus: { value: {color.blue.500} }, error: { value: {color.red.500} } } }, spacing: { xs: { value: 4px }, sm: { value: 8px }, md: { value: 16px }, lg: { value: 24px }, xl: { value: 32px }, 2xl: { value: 48px } }, radius: { sm: { value: 4px }, md: { value: 8px }, lg: { value: 16px }, full: { value: 9999px } }, shadow: { sm: { value: 0 1px 2px rgba(0,0,0,0.05) }, md: { value: 0 4px 6px rgba(0,0,0,0.07) }, lg: { value: 0 10px 25px rgba(0,0,0,0.1) } } }使用 Style Dictionary 做转译Style Dictionary 是设计 Token 领域最成熟的转译工具Amazon 开源已维护 7 年。// build-tokens.js const StyleDictionary require(style-dictionary); const sd StyleDictionary.extend({ source: [ tokens/primitives/**/*.json, tokens/semantics/**/*.json, ], platforms: { /** CSS 变量输出 */ css: { transformGroup: css, buildPath: dist/css/, files: [ { destination: tokens.css, format: css/variables, options: { outputReferences: true, // 保留引用关系 }, }, ], /** 暗黑模式通过>/* dist/css/tokens.css (构建产物) */ :root { --color-text-primary: #1A1A2E; --color-text-secondary: #64748B; --color-background-primary: #FFFFFF; --color-background-secondary: #F8FAFC; } [data-themedark] { --color-text-primary: #E2E8F0; --color-text-secondary: #94A3B8; --color-background-primary: #0F172A; --color-background-secondary: #1E293B; } /* 或使用 prefers-color-scheme */ media (prefers-color-scheme: dark) { :root:not([data-themelight]) { --color-text-primary: #E2E8F0; --color-text-secondary: #94A3B8; --color-background-primary: #0F172A; --color-background-secondary: #1E293B; } }Token 变更的 CI 检查# .github/workflows/token-check.yml name: Design Token Consistency Check on: pull_request: paths: - tokens/** jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Build Tokens run: npx style-dictionary build - name: Check Token Changes run: | # 检测是否有意外的 Token 变更 git diff --exit-code dist/ || { echo ⚠️ Token 构建产物有变更请提交 dist/ 目录 exit 1 } - name: Validate Token References run: node scripts/validate-token-refs.js - name: Check Contrast Ratios run: node scripts/check-contrast.js - name: Generate Token Changelog run: node scripts/token-diff.js token-changelog.md - name: Comment on PR uses: actions/github-scriptv7 with: script: | const fs require(fs); const changelog fs.readFileSync(token-changelog.md, utf8); github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: ## 设计 Token 变更清单\n\n${changelog} });四、常见踩坑与避坑指南Token 太多没人知道该用哪个建议控制在 80-120 个语义 Token。多了就说明你的层级设计有问题或者有 Token 该合并。设计师不在 Figma 里用 Token 名这是落地最大的障碍。解决方案是使用 Figma Tokens 插件让设计师在 Figma 里直接用 Token 名和代码一一对应。Token 命名是政治问题spacing-md还是spacing-3color-primary还是color-brand这类命名分歧本质是团队对什么是设计语言的共识问题。建议先定规范文档再建 Token。跨平台 Token 不可能 100% 一致iOS 的 SF Pro 字体和 Android 的 Roboto 字体渲染不同同一个 Token 值会产出视觉差异。接受 95% 的一致性5% 让平台特性接管。五、总结设计 Token 体系不是一堆 JSON 文件 一个 SD 构建脚本它是设计决策的工程化。三层架构基础 → 语义 → 组件保证了灵活性CTI 命名规范保证了可读性Style Dictionary 保证了多平台一致性。最重要的是——当这个体系真正运转起来之后设计师改了一个色值的工程影响从改 89 处代码变成了改一行 JSON 跑一次构建。这才是设计系统该有的样子。作者李慕杰Leo / 8limujie一个花了三年时间、终于让设计师和前端对色值的定义达成共识的前端匠人
设计 Token 体系搭建从前端变量到跨平台一致性的工程化实践一、设计师在 Figma 里改了一个色值前端要在 37 个文件里改 89 处如果你经历过这个场景你需要一个设计 Token 体系。设计 TokenDesign Token这个概念被提出快十年了但在国内前端团队的落地情况依然不乐观。问题不在于不知道 Token 是什么而在于怎么在工程里把它用起来而不只是一堆 JSON 文件。设计 Token 的本质是将设计决策抽象为平台无关的变量然后通过转译工具生成各平台Web、iOS、Android、Flutter的原生代码。它让设计师在 Figma 改一个主色这件事的工程影响从全局搜索替换变成改一行 JSON自动生成所有平台的代码。这篇文章我会从 Token 的层级设计、命名规范、转译工具链、CI 集成四个维度给你一套可以直接照搬的 Token 体系搭建方案。二、设计 Token 的层级架构为什么需要三层很多人直接把 Figma 里的色值写成 CSS 变量这就跳过了最重要的语义层// 错误基础值和语义值混在一起 { color-primary: #3B82F6, color-primary-hover: #2563EB }这种结构的致命问题是当你想在暗黑模式下把主色从#3B82F6换成#93C5FD时你需要改的是语义 Token而不是基础色值。如果基础和语义混在一起你就失去了一个值关联多个语义的灵活性// 正确三层分离 // primitives.json { blue: { 500: { value: #3B82F6 }, 600: { value: #2563EB }, 300: { value: #93C5FD } } } // semantics.json { color: { primary: { value: {blue.500} }, primary-hover: { value: {blue.600} }, primary-on-dark: { value: {blue.300} } } } // 暗黑模式只需要这一层 // semantics-dark.json { color: { primary: { value: {blue.300} }, primary-hover: { value: {blue.200} } } }三、Token 体系的完整工程实现命名规范使用 CTICategory / Type / Item结构[category]-[type]-[item]-[variant]-[state] 示例 color-background-primary-hover font-size-heading-xl spacing-layout-section-gap radius-component-button shadow-elevation-card完整的 Token Map 示例{ color: { text: { primary: { value: {color.neutral.900} }, secondary: { value: {color.neutral.600} }, disabled: { value: {color.neutral.400} }, inverse: { value: {color.neutral.0} } }, background: { primary: { value: {color.neutral.0} }, secondary: { value: {color.neutral.50} }, overlay: { value: rgba(0, 0, 0, 0.5) } }, border: { default: { value: {color.neutral.200} }, focus: { value: {color.blue.500} }, error: { value: {color.red.500} } } }, spacing: { xs: { value: 4px }, sm: { value: 8px }, md: { value: 16px }, lg: { value: 24px }, xl: { value: 32px }, 2xl: { value: 48px } }, radius: { sm: { value: 4px }, md: { value: 8px }, lg: { value: 16px }, full: { value: 9999px } }, shadow: { sm: { value: 0 1px 2px rgba(0,0,0,0.05) }, md: { value: 0 4px 6px rgba(0,0,0,0.07) }, lg: { value: 0 10px 25px rgba(0,0,0,0.1) } } }使用 Style Dictionary 做转译Style Dictionary 是设计 Token 领域最成熟的转译工具Amazon 开源已维护 7 年。// build-tokens.js const StyleDictionary require(style-dictionary); const sd StyleDictionary.extend({ source: [ tokens/primitives/**/*.json, tokens/semantics/**/*.json, ], platforms: { /** CSS 变量输出 */ css: { transformGroup: css, buildPath: dist/css/, files: [ { destination: tokens.css, format: css/variables, options: { outputReferences: true, // 保留引用关系 }, }, ], /** 暗黑模式通过>/* dist/css/tokens.css (构建产物) */ :root { --color-text-primary: #1A1A2E; --color-text-secondary: #64748B; --color-background-primary: #FFFFFF; --color-background-secondary: #F8FAFC; } [data-themedark] { --color-text-primary: #E2E8F0; --color-text-secondary: #94A3B8; --color-background-primary: #0F172A; --color-background-secondary: #1E293B; } /* 或使用 prefers-color-scheme */ media (prefers-color-scheme: dark) { :root:not([data-themelight]) { --color-text-primary: #E2E8F0; --color-text-secondary: #94A3B8; --color-background-primary: #0F172A; --color-background-secondary: #1E293B; } }Token 变更的 CI 检查# .github/workflows/token-check.yml name: Design Token Consistency Check on: pull_request: paths: - tokens/** jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Build Tokens run: npx style-dictionary build - name: Check Token Changes run: | # 检测是否有意外的 Token 变更 git diff --exit-code dist/ || { echo ⚠️ Token 构建产物有变更请提交 dist/ 目录 exit 1 } - name: Validate Token References run: node scripts/validate-token-refs.js - name: Check Contrast Ratios run: node scripts/check-contrast.js - name: Generate Token Changelog run: node scripts/token-diff.js token-changelog.md - name: Comment on PR uses: actions/github-scriptv7 with: script: | const fs require(fs); const changelog fs.readFileSync(token-changelog.md, utf8); github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: ## 设计 Token 变更清单\n\n${changelog} });四、常见踩坑与避坑指南Token 太多没人知道该用哪个建议控制在 80-120 个语义 Token。多了就说明你的层级设计有问题或者有 Token 该合并。设计师不在 Figma 里用 Token 名这是落地最大的障碍。解决方案是使用 Figma Tokens 插件让设计师在 Figma 里直接用 Token 名和代码一一对应。Token 命名是政治问题spacing-md还是spacing-3color-primary还是color-brand这类命名分歧本质是团队对什么是设计语言的共识问题。建议先定规范文档再建 Token。跨平台 Token 不可能 100% 一致iOS 的 SF Pro 字体和 Android 的 Roboto 字体渲染不同同一个 Token 值会产出视觉差异。接受 95% 的一致性5% 让平台特性接管。五、总结设计 Token 体系不是一堆 JSON 文件 一个 SD 构建脚本它是设计决策的工程化。三层架构基础 → 语义 → 组件保证了灵活性CTI 命名规范保证了可读性Style Dictionary 保证了多平台一致性。最重要的是——当这个体系真正运转起来之后设计师改了一个色值的工程影响从改 89 处代码变成了改一行 JSON 跑一次构建。这才是设计系统该有的样子。作者李慕杰Leo / 8limujie一个花了三年时间、终于让设计师和前端对色值的定义达成共识的前端匠人
