设计系统与代码同步，需要把语义 Token、组件属性、状态和版本对应起来。同步颜色文件只是第一步；如果按钮的禁用、加载、焦点状态没有同一套规则，设计稿和实现仍会持续偏离。先约定共同语言，再建立可追踪的变更与验收流程。
可以在墨刀设计中维护设计组件和页面，再由团队建立与代码组件的映射；不要把有了设计库等同于两端已经自动同步。
先区分三层 Token
以主要操作按钮为例，基础 Token 表达原始值，如某个色值；语义 Token 表达用途，如主要操作背景；组件 Token 表达特定组件与状态，如主要按钮悬停背景。页面优先通过语义或组件层引用，不应到处直接填同一个色值。
| 层级 | 示例名称 | 解决什么问题 |
|---|---|---|
| 基础 | color.blue.600 | 集中维护原始色值 |
| 语义 | color.action.primary | 表达主要操作用途，可按主题映射 |
| 组件 | button.primary.hover.background | 表达按钮变体与状态 |
| 代码引用 | 项目约定的 CSS 变量或主题对象 | 让实现能定位到同一条规则 |
上面的名称只是命名写法，实际应沿用项目约定。关键是名称稳定、含义明确、设计与代码可以互查；不要在设计侧叫“品牌蓝”，代码侧叫“blue2”，变更记录又写“按钮新颜色”。
组件映射表要覆盖属性和状态
为 Button 建立属性矩阵：用途、尺寸、是否有图标、是否加载、是否禁用；同时列出默认、悬停、按下、键盘焦点和错误相关表现。每个设计变体对应哪个代码组件属性，缺失或不支持的组合要直接写出来。
| 设计侧约定 | 代码侧需明确 | 验收页面 |
|---|---|---|
| 主要按钮 + 加载 | loading 时按钮文案、图标和点击行为 | 表单提交页 |
| 仅图标按钮 | 可访问名称、最小操作区域 | 列表操作栏 |
| 禁用按钮 | 不可操作原因在何处解释 | 权限不足或条件未满足的任务 |
| 危险操作 | 确认与不可逆提示是否独立处理 | 删除或撤销流程 |
用一个变更单把修改传到两端
- 提出原因：写明要解决的任务，不只写“视觉升级”。
- 列影响：指出 Token、组件、状态和使用页面，识别是否改变交互行为。
- 设计验证：检查组件矩阵和真实页面中的文本、间距、窄屏与主题表现。
- 实现映射：研发说明变量、组件 API、版本与兼容办法。
- 共同验收：在表单、列表、弹窗等代表页面核对，而非只比一张组件截图。
- 记录发布：保留版本、迁移说明、负责人和可回退的旧版本。
新增、修改、废弃分开记录。改 Token 值可能影响所有引用页面；改组件属性名会影响调用方。对破坏性变更提供迁移步骤，必要时保留兼容名称，并说明何时移除。不要在一个无说明的文件覆盖中完成所有变化。
按钮换色后，为什么线上仍可能不一致
原因常见于三处：页面有硬编码值，旧组件包仍在使用，某个状态没有引用语义 Token。检查时先定位具体页面和状态，再回查变量与版本。只在页面上补一个 CSS 覆盖会暂时好看，却可能制造下次升级的新漂移。
漂移记录可用：页面｜组件/状态｜设计版本｜代码版本｜差异截图｜影响任务｜负责人。先分清是规范本身需要变更，还是实现没有遵守规范，再决定改哪一端。
一个主要按钮换色的完整变更示例
假设团队决定调整主要操作背景。先在基础色中增加或修改目标值，再检查语义映射；主要按钮、主要链接或焦点指示是否都应该受到影响，不能只因为引用相同蓝色就一起改。若用途不同，应拆开语义 Token，而不是继续复用一个模糊名称。
随后检查默认、悬停和按下状态的层级，确认文字对比、禁用表现和深色主题。设计交付变更单，研发更新变量与组件包，在表单提交页验证长文案、加载和错误恢复。发布记录包含设计版本、代码版本和已验证页面，出现问题时能够定位是哪次映射变化。
版本迁移和页面例外怎么处理
旧页面不能一次迁移时，可以按模块安排升级，保留明确的兼容期限。变更单列出未迁移页面及原因；新增页面使用当前规范，不再复制旧值。移除旧名称前检查调用范围，确认没有业务页面仍在引用。
业务确实需要例外时，记录适用页面、原因和负责人，把覆盖范围限制在该场景。不要因为一个营销页面需要更大的按钮，就把公共组件的所有尺寸一起改变；也不要让例外成为没有说明的长期复制。
责任可以按环节分工：设计维护语义和状态规则，研发维护组件 API 与兼容性，业务团队验证真实任务。每次评审围绕同一个变更单，避免三份文档各写一套“最新规范”。
验收要看能不能完成操作
除了视觉比对，还要检查焦点可见、键盘操作、长文本、多语言、窄屏、主题和错误反馈。禁用态不能只降低透明度而不解释原因；加载态不能让用户不知道是否已经提交。实际实现仍需运行项目测试及可访问性检查。
不稳定的新业务先在页面级验证，确认出现重复使用需求后再沉淀进组件库。设计系统的目标是减少重复决策，不是无限增加组件。交付物保持精简：Token 与组件映射表、变更单、验证页面、版本和迁移记录，足以让下一位维护者接手。
从墨刀设计中的一个主要按钮开始，整理默认、悬停、加载和禁用状态，再请研发填上对应变量、组件属性与版本。让这个按钮先在一张真实表单中对齐，再推广到组件库的其他部分。
