设计系统搭建实战：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-themedark] { --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-themehigh-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 ): PromiseSyncResult { 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 规则逐步消除硬编码值。