设计 Token 自动同步：别让颜色停在设计稿里

一、Token 的价值是跨工具一致，而不是换个名字存颜色

设计 Token 把颜色、字号、间距、圆角、阴影和动效参数变成可管理变量。它的意义不只是让设计稿看起来规范，而是让设计工具、前端代码、移动端代码和文档使用同一套语义。否则设计稿里叫primary-500，代码里写#1677ff，组件库里又叫brandBlue，一致性会慢慢失控。

自动同步要解决两个问题：谁是 Token 的源头，以及变更如何进入代码。源头可以是设计工具、Token 仓库或设计系统平台；进入代码时要经过版本、评审和测试。不要让设计师随手改一个颜色，就自动影响生产环境。Token 也是代码资产，需要发布流程。

二、同步链路：从设计语义到多端产物

flowchart TD A[Token 源文件] --> B[Schema 校验] B --> C[构建转换] C --> D[Web CSS Variables] C --> E[Flutter Theme] C --> F[文档站] D --> G[组件库发布] E --> G

Token 应该按语义分层。基础层可以是原始色板，例如blue.500；语义层是业务含义，例如color.action.primary.background；组件层是具体组件变量，例如button.primary.bg。项目中真正大量使用的应是语义层和组件层，而不是到处引用基础色板。

多端同步时，命名规范要稳定。Web 需要 CSS Variables，Flutter 需要 ThemeData 或常量类，小程序可能需要 JSON 或 WXSS 变量。构建工具可以把同一份 Token 转成不同平台格式，但前提是源文件结构清晰。

三、Token 源文件：先做 Schema 校验

下面是一份简化的 Token 文件。实际项目中可以加入描述、暗色模式和废弃标记。

{ "color": { "action": { "primary": { "background": { "value": "#2563EB", "type": "color" }, "text": { "value": "#FFFFFF", "type": "color" } } } }, "radius": { "control": { "value": "6px", "type": "dimension" } } }

Schema 校验至少检查字段完整性、颜色格式、单位合法性、命名层级和重复定义。还要避免直接删除正在被代码使用的 Token。可以引入废弃周期：先标记 deprecated，组件库迁移完成后再删除。这样能减少破坏性变更。

构建产物也要可读。Web 端可以生成:root { --color-action-primary-background: #2563EB; }，Flutter 端可以生成静态常量或 ThemeExtension。自动生成不代表不可理解，研发仍然需要能追踪某个变量来自哪里。

四、变更治理：Token 发布需要回归测试

Token 变更可能影响大面积界面。一个背景色变浅，可能导致文字对比不足；一个间距变大，可能让移动端按钮换行；一个圆角变化，可能破坏组件截图基线。因此 Token 发布应触发视觉回归、无障碍对比检查和组件快照测试。

设计评审也要从“颜色好不好看”升级为“语义是否正确”。例如危险按钮使用红色，不应直接引用red.500，而应引用color.danger.background。当暗色模式或品牌换肤出现时，语义 Token 才能稳定映射。

最后要有版本记录。Token 包可以独立发版，组件库声明依赖版本。业务项目升级 Token 时，知道引入了哪些视觉变化。没有版本，设计系统会变成一组难以追踪的全局变量。

五、总结

设计 Token 自动同步的核心是语义、校验、转换和发布治理。让 Token 从设计稿进入代码，不是复制颜色值，而是建立跨端一致的设计语言。源文件清晰、Schema 严格、变更可回归，Token 才能真正成为设计和工程的共同资产。