当 Token 在三个平台跳着不同的舞设计 Token 多平台同步的 Web、iOS、Android 一致性方案一、深度引言与场景痛点设计 Token 是设计系统的脉搏信号在 Web 端它是 CSS 自定义属性var(--color-primary)在 iOS 端它是 Swift Color 扩展UIColor.brandPrimary在 Android 端它是 XML Resourcecolor/brand_primary。同一个脉搏三种表达——格式不同、命名不同、数值精度不同、色彩空间不同。多平台同步的核心痛点不是能不能传而是传了之后三个平台看起来是否一样。Web 端的#3B82F6在 iOS 的 UIKit 渲染引擎中可能偏暗 2%在 Android 的 Material 渲染引擎中可能偏亮 1%——三个平台使用不同的色彩空间和渲染管线同一个 hex 值在视觉上可能不一致。同步不只是格式转换更是跨平台视觉一致性校准。二、底层机制与原理深度剖析多平台 Token 同步的三层管道提取与标准化、格式转换、视觉一致性校准。每层解决一类跨平台问题。flowchart TD A[设计 Token 源JSON 中间格式] -- B[提取与标准化层] B -- B1[统一色彩空间所有色值转为 OKLCH] B -- B2[统一数值精度间距值保留 2 位小数] B -- B3[统一命名规范kebab-case 中间命名] B1 B2 B3 -- C[格式转换层] C -- C1[Web 输出CSS 自定义属性] C -- C2[iOS 输出Swift Color / Font 扩展] C -- C3[Android 输出XML Resource ThemeOverlay] C1 C2 C3 -- D[视觉一致性校准层] D -- D1[Web 渲染基准截图] D -- D2[iOS 渲染对比截图] D -- D3[Android 渲染对比截图] D -- D4[跨平台像素偏差 2% 时自动校准] D1 D2 D3 D4 -- E[三个平台同步发布]提取与标准化层解决格式异构问题。JSON 中间格式是三个平台的共享源——所有 Token 值先转为 JSON再从 JSON 分发到各平台。标准化把所有色彩值转为 OKLCH 空间感知均匀所有间距值转为 dp 单位密度无关像素所有字号值转为 sp 单位可缩放像素。标准化确保同一个 Token 在不同平台上使用相同的数值基准。格式转换层解决语法异构问题。CSS Variable 用--color-primary: #3B82F6;声明Swift 用static let brandPrimary UIColor(red: 0.231, green: 0.510, blue: 0.965, alpha: 1.0)声明Android XML 用color namebrand_primary#3B82F6/color声明。三种语法由同一份 JSON 自动生成命名规则各平台独立CSS 用 kebab-caseSwift 用 camelCaseAndroid 用 snake_case。视觉一致性校准层解决渲染异构问题。三个平台的色彩渲染管线不同——Web 使用 sRGB 空间iOS 使用 Display P3 空间广色域Android 使用 sRGB 但有自适应色调映射。同一个 OKLCH 色值在三个平台上转换回各平台原生空间时可能产生微小偏差。校准层通过截屏对比检测偏差超过 2% 时自动微调色值补偿。三、生产级代码实现与最佳实践JSON 中间格式定义// types/design-token.ts interface DesignToken { name: string; // 中间命名kebab-case value: TokenValue; type: color | spacing | font-size | font-weight | border-radius | opacity; platforms: PlatformSpecific; // 平台特定配置 } interface TokenValue { oklch?: { L: number; C: number; H: number }; // 色彩值OKLCH 空间 srgb?: string; // sRGB hex 值Web 端使用 dp?: number; // 间距值密度无关像素 sp?: number; // 字号值可缩放像素 } interface PlatformSpecific { web?: { cssName: string; cssValue: string }; ios?: { swiftName: string; swiftValue: string }; android?: { xmlName: string; xmlValue: string }; } // Token JSON 示例 const tokens: DesignToken[] [ { name: color-primary, value: { oklch: { L: 0.54, C: 0.25, H: 258 }, srgb: #3B82F6 }, type: color, platforms: { web: { cssName: --color-primary, cssValue: #3B82F6 }, ios: { swiftName: brandPrimary, swiftValue: UIColor(red: 0.231, green: 0.510, blue: 0.965, alpha: 1.0) }, android: { xmlName: brand_primary, xmlValue: #3B82F6 }, } }, { name: spacing-4, value: { dp: 16 }, type: spacing, platforms: { web: { cssName: --spacing-4, cssValue: 16px }, ios: { swiftName: spacing4, swiftValue: 16 }, android: { xmlName: spacing_4, xmlValue: 16dp }, } } ];CSS 输出生成// scripts/token-sync/generate-css.ts function generateCSSTokens(tokens: DesignToken[]): string { const lines tokens.map(t { const web t.platforms.web; return ${web!.cssName}: ${web!.cssValue};; }); return :root {\n${lines.join(\n)}\n}\n; }iOS Swift 输出生成// scripts/token-sync/generate-swift.ts function generateSwiftTokens(tokens: DesignToken[]): string { const colorTokens tokens.filter(t t.type color); const spacingTokens tokens.filter(t t.type spacing); const fontTokens tokens.filter(t t.type font-size); let output import UIKit\n\nextension UIColor {\n; for (const t of colorTokens) { const ios t.platforms.ios!; output static let ${ios.swiftName} ${ios.swiftValue}\n; } output }\n\nextension CGFloat {\n; for (const t of spacingTokens) { const ios t.platforms.ios!; output static let ${ios.swiftName} ${ios.swiftValue}\n; } output }\n; return output; }Android XML 输出生成// scripts/token-sync/generate-xml.ts function generateAndroidTokens(tokens: DesignToken[]): string { const colorTokens tokens.filter(t t.type color); const spacingTokens tokens.filter(t t.type spacing); let colorsXml resources\n; for (const t of colorTokens) { const android t.platforms.android!; colorsXml color name${android.xmlName}${android.xmlValue}/color\n; } colorsXml /resources\n; let dimensXml resources\n; for (const t of spacingTokens) { const android t.platforms.android!; dimensXml dimen name${android.xmlName}${android.xmlValue}/dimen\n; } dimensXml /resources\n; return colorsXml \n dimensXml; }CI 同步流程编排# .github/workflows/token-sync.yml name: Design Token Multi-Platform Sync on: push: paths: - design-tokens/**/*.json jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: npm ci # 生成三个平台的 Token 文件 - run: node scripts/token-sync/generate-css.ts - run: node scripts/token-sync/generate-swift.ts - run: node scripts/token-sync/generate-xml.ts # 视觉一致性校准截屏对比 - run: node scripts/token-sync/visual-calibration.ts # 自动提交到三个平台的仓库 - run: git add src/styles/tokens.css - run: | git config user.name Token Sync Bot git commit -m sync: 更新设计 Token git push四、边界分析与架构权衡色彩空间的跨平台差异。iOS 支持 Display P3 广色域Web 和 Android 默认使用 sRGB。同一个 OKLCH 色值在 P3 空间中的 sRGB 回退值可能更饱和——P3 能表达的色域比 sRGB 更广超出 sRGB 范围的色值在 sRGB 设备上会被裁剪。解决方案为 iOS 生成两套色值——P3 版本利用广色域和 sRGB 版本用于 P3 不支持的设备Web 和 Android 只使用 sRGB 版本。间距单位的跨平台映射。Web 使用 pxiOS 使用 pt逻辑像素Android 使用 dp密度无关像素。在标准屏幕密度下1x 倍率1px 1pt 1dp三者数值相同。但在高密度屏幕上2x/3x 倍率物理像素与逻辑像素的比值不同——iOS 的 16pt 在 2x 屏幕上是 32 物理像素Android 的 16dp 在 2x 屏幕上也是 32 物理像素。映射关系在数值上一致但渲染管线不同。命名规范的跨平台碰撞。CSS 的 kebab-case--color-primary、Swift 的 camelCasebrandPrimary、Android 的 snake_casebrand_primary——三种命名规范自动转换但如果 Token 名称中包含数字如blue-500Swift 的命名规则不允许数字开头500Blue不合法需要调整命名顺序blue500。转换器需要处理每个平台的命名合法性约束。同步频率与一致性延迟。Token 变更后三个平台的同步有延迟——Web 端几分钟内更新CI 自动提交iOS 和 Android 端需要各自的 CI 管道处理总延迟可能 1-2 小时。如果设计师在 Figma 中修改了主色Web 端已经更新但 iOS 端还没更新用户在两个平台上看到的品牌色不一致。解决方案同步窗口期标注——在 Token 变更后的 2 小时内标注为过渡期设计系统文档中提示iOS/Android 端正在同步中。五、总结设计 Token 的多平台同步是三条舞蹈线的对齐——Web 跳 CSS 节拍iOS 跳 Swift 节拍Android 跳 XML 节拍三条线共享同一个脉搏信号JSON 中间格式但各自的表达方式和渲染管线不同。同步不只是格式转换更是跨平台视觉一致性的校准。三层管道——标准化、转换、校准——逐层把异构问题解决标准化统一色彩空间和数值精度转换适配各平台语法和命名规则校准检测并补偿渲染偏差。三层叠加后的同步结果让三个平台上的同一个 Token 在视觉上看起来是一样的在代码上用各自的语法表达。同步的终极目标是让设计系统的脉搏信号在三条舞蹈线上同时跳动——设计师修改一个 Token几分钟内 Web、iOS、Android 三个平台同步更新。脉搏信号的一致传递才是设计系统跨平台一致性的真正保障。