设计系统搭建实战：Token 管理体系与多端样式同步方案

设计系统搭建实战：Token 管理体系与多端样式同步方案

一、样式碎片化的根源——没有设计系统的团队如何失控

当团队规模从 3 人增长到 15 人时，UI 一致性会以可预测的方式崩塌：同一产品中出现 7 种不同的蓝色、3 种不同的圆角值、5 种不同的按钮高度。这些碎片化并非工程师的疏忽，而是缺乏系统性约束的必然结果——在没有设计系统的项目中，每个开发者都在用自己的"审美直觉"填补设计规范的空白。

设计系统的核心目标不是限制创造力，而是将"可标准化的决策"从人的判断中剥离出来，让团队将有限的注意力集中在不可标准化的创新上。Token 管理体系是设计系统的基石，它将视觉决策编码为可引用、可追踪、可同步的原子单位。

二、Token 管理体系的架构设计

2.1 Token 的三层架构

flowchart TD A[原始层 Raw Tokens] --> B[语义层 Semantic Tokens] B --> C[组件层 Component Tokens] subgraph 原始层 A1[color-blue-50: #EFF6FF] A2[color-blue-500: #3B82F6] A3[color-blue-900: #1E3A8A] A4[spacing-1: 4px] A5[radius-sm: 4px] end subgraph 语义层 B1[color-primary: var--color-blue-500] B2[color-primary-hover: var--color-blue-600] B3[color-surface: var--color-neutral-0] B4[spacing-gap: var--spacing-4] end subgraph 组件层 C1[button-bg: var--color-primary] C2[button-bg-hover: var--color-primary-hover] C3[button-padding: var--spacing-gap] C4[card-bg: var--color-surface] end

三层架构的核心原则是"单向依赖"：组件层只能引用语义层，语义层只能引用原始层，禁止跨层引用和反向依赖。这一约束确保了主题切换时只需修改语义层的映射关系，组件层无需任何变更。

2.2 Token 的分类与命名规范

flowchart LR A[Token 分类] --> B[全局 Token] A --> C[别名 Token] A --> D[组件 Token] B --> B1[color.blue.500] B --> B2[spacing.4] B --> B3[radius.md] C --> C1[color.primary] C --> C2[spacing.component.gap] D --> D1[button.background] D --> D2[card.padding]

命名规范遵循{类别}.{子类别}.{层级}的结构，使用点号分隔而非连字符，以便在代码中通过前缀快速过滤和批量操作。

三、生产级 Token 管理与多端同步实现

3.1 Token 源文件与多格式输出

Token 的单一数据源（Single Source of Truth）使用 JSON 或 YAML 格式存储，通过构建工具转换为各平台所需的格式：

{ "color": { "blue": { "50": { "value": "#EFF6FF", "type": "color" }, "100": { "value": "#DBEAFE", "type": "color" }, "500": { "value": "#3B82F6", "type": "color" }, "600": { "value": "#2563EB", "type": "color" }, "900": { "value": "#1E3A8A", "type": "color" } }, "neutral": { "0": { "value": "#FFFFFF", "type": "color" }, "50": { "value": "#F9FAFB", "type": "color" }, "900": { "value": "#111827", "type": "color" } } }, "spacing": { "1": { "value": "4px", "type": "spacing" }, "2": { "value": "8px", "type": "spacing" }, "4": { "value": "16px", "type": "spacing" }, "6": { "value": "24px", "type": "spacing" } }, "radius": { "sm": { "value": "4px", "type": "borderRadius" }, "md": { "value": "8px", "type": "borderRadius" }, "lg": { "value": "12px", "type": "borderRadius" } } }

3.2 构建管线：从 JSON 到多平台输出

import StyleDictionary from 'style-dictionary'; interface TokenBuildConfig { source: string; platforms: { css: { output: string }; scss: { output: string }; flutter: { output: string }; ios: { output: string }; }; } class TokenBuildPipeline { private sd: StyleDictionary.Core; constructor(config: TokenBuildConfig) { this.sd = StyleDictionary.extend({ source: [config.source], platforms: { css: { transformGroup: 'css', buildPath: config.platforms.css.output, files: [{ destination: 'tokens.css', format: 'css/variables', options: { outputReferences: true }, }], }, scss: { transformGroup: 'scss', buildPath: config.platforms.scss.output, files: [{ destination: '_tokens.scss', format: 'scss/variables', options: { outputReferences: true }, }], }, flutter: { transformGroup: 'flutter', buildPath: config.platforms.flutter.output, files: [{ destination: 'tokens.dart', format: 'flutter/class.dart', className: 'DesignTokens', }], }, }, }); } build(): void { this.sd.buildAllPlatforms(); } }

3.3 主题切换与暗色模式实现

/* 亮色主题：语义层 Token 的默认映射 */ :root { --color-primary: var(--color-blue-500); --color-primary-hover: var(--color-blue-600); --color-surface: var(--color-neutral-0); --color-surface-elevated: var(--color-neutral-50); --color-text-primary: var(--color-neutral-900); --color-text-secondary: var(--color-neutral-500); --color-border: var(--color-neutral-200); } /* 暗色主题：仅修改语义层映射，组件层无需变更 */ [data-theme="dark"] { --color-primary: var(--color-blue-400); --color-primary-hover: var(--color-blue-300); --color-surface: var(--color-neutral-900); --color-surface-elevated: var(--color-neutral-800); --color-text-primary: var(--color-neutral-50); --color-text-secondary: var(--color-neutral-400); --color-border: var(--color-neutral-700); } /* 高对比度主题：满足 WCAG AAA 标准 */ [data-theme="high-contrast"] { --color-primary: var(--color-blue-700); --color-primary-hover: var(--color-blue-800); --color-text-primary: #000000; --color-text-secondary: #333333; --color-border: #000000; } /* 组件层 Token：跨主题通用 */ :root { --button-bg: var(--color-primary); --button-bg-hover: var(--color-primary-hover); --button-text: var(--color-surface); --card-bg: var(--color-surface-elevated); --card-border: var(--color-border); }

3.4 Figma 与代码的双向同步

interface SyncResult { added: TokenDiff[]; modified: TokenDiff[]; removed: TokenDiff[]; conflicts: TokenConflict[]; } class FigmaTokenSync { /** * 比较 Figma 中的 Token 与代码仓库中的 Token * 生成差异报告 */ async diff( figmaTokens: TokenSet, codeTokens: TokenSet ): Promise<SyncResult> { const added: TokenDiff[] = []; const modified: TokenDiff[] = []; const removed: TokenDiff[] = []; const conflicts: TokenConflict[] = []; // 检测新增 Token for (const [name, token] of Object.entries(figmaTokens)) { if (!codeTokens[name]) { added.push({ name, value: token.value, source: 'figma' }); } else if (codeTokens[name].value !== token.value) { // 检测修改：值不同时判断是否为冲突 if (codeTokens[name].lastModified > token.lastModified) { conflicts.push({ name, figmaValue: token.value, codeValue: codeTokens[name].value, resolution: 'pending', }); } else { modified.push({ name, oldValue: codeTokens[name].value, newValue: token.value, source: 'figma', }); } } } // 检测删除 Token for (const name of Object.keys(codeTokens)) { if (!figmaTokens[name]) { removed.push({ name, value: codeTokens[name].value, source: 'code' }); } } return { added, modified, removed, conflicts }; } }

四、设计系统落地的阻力与权衡

4.1 Token 粒度的两难选择

Token 粒度过细（如为每个按钮状态定义独立 Token）会导致 Token 数量爆炸，维护成本极高；粒度过粗（如只定义--color-primary）则无法表达组件级别的视觉差异。工程实践中建议采用"80/20 原则"：80% 的组件使用语义层 Token，仅 20% 的高频核心组件（按钮、输入框、卡片）定义组件层 Token。

4.2 多端同步的时间差问题

Figma 插件同步 Token 存在网络延迟和手动触发的问题，设计师修改 Token 后，代码仓库可能数小时后才同步。在这段时间差内，设计稿与代码的 Token 定义不一致，可能导致视觉偏差。建议在 CI 流水线中加入 Token 一致性检查，当检测到 Figma 与代码的 Token 差异超过阈值时，自动通知相关团队。

4.3 渐进式迁移的兼容性成本

存量项目迁移到设计系统时，不可能一次性替换所有硬编码值。渐进式迁移意味着 Token 体系与硬编码值长期共存，这增加了样式冲突的风险。建议采用"新代码强制 Token，旧代码逐步迁移"的策略：ESLint 规则禁止新增硬编码颜色和间距值，存量硬编码值在每次涉及相关文件修改时顺带迁移。

4.4 设计系统的版本管理

设计系统作为独立包发布时，版本号必须与消费方的依赖管理对齐。Breaking change（如删除 Token、修改 Token 语义）需要遵循 semver 规范升级主版本号。但在实际操作中，"修改 Token 语义"的判断标准模糊——将--color-primary从蓝色改为紫色，对某些项目是 breaking change，对另一些项目则是预期行为。建议在设计系统文档中明确每个 Token 的"稳定性等级"：stable（禁止 breaking change）、evolving（允许 minor 变更）、experimental（随时可能变更）。

五、总结

Token 管理体系是设计系统的骨架，三层架构（原始层、语义层、组件层）实现了视觉决策的分层抽象与单向依赖。多端同步方案确保了设计稿与代码的一致性，主题切换通过语义层映射实现零成本扩展。

落地路线建议：第一步，定义原始层 Token，覆盖颜色、间距、圆角、字体四个维度；第二步，建立语义层映射，实现亮色/暗色主题切换；第三步，搭建 Style Dictionary 构建管线，输出 CSS、SCSS、Flutter 多平台格式；第四步，实现 Figma 与代码的 Token 同步工具，在 CI 中加入一致性检查；第五步，制定渐进式迁移策略，通过 ESLint 规则逐步消除硬编码值。