设计系统同步 是做什么的?
概述
当设计系统已经存在于代码中时,设计工具应当镜像它,而非重构它。
- 导入将代码的令牌和用户选择的组件引入工具,并使用相同的名称。
- 导出将工具指南中的更改通过审查后的差异(diff)反馈到代码中。
项目根目录下的一个小文件 design-sync.json 会记录上次同步的内容。代码保持真实来源地位,除非用户另有说明:变更先在工具中绘制,然后通过批准的导出落地到代码中。
何时使用
- 一个设计任务即将在已有代码设计系统但工具中尚无指南的项目中启动。
craft-setup和craft会将任务转交给本技能。 - “导入 / 将我们的设计系统(令牌、组件)带入 Paper / Figma / 设计工具。”
- “应用 / 推送 / 同步指南的更改到代码。”
何时不使用
- 代码中没有设计系统:使用
craft-system(创建模式)。 - 在该项目中需要进行审查、生成选项或进行小编辑:这些技能将直接基于现有代码工作。
- 用户口述了单个令牌值(例如“在代码中将强调色设为 #3d7f69”):直接编辑它,更新
design-sync.json中对应的名称,并说明其影响范围。
开始之前
- 如果存在,请阅读
DESIGN.md(品牌团队会说明设计系统所在位置)和design-sync.json。 - 在
references/adapters/中选择工具对应的适配器(paper.md、figma.md、html.md)。如果没有适配器与您的工具匹配,则在您的工具中执行相同操作,并说明您手动映射了哪些部分。如果根本没有设计工具,则使用 HTML 构建(html.md)。如果只有图像,则说明从中读取的值仅为估算值。
design-sync.json
{
"source": "packages/ui/tokens.css",
"tool": "paper: file 'Fieldnote', page 'Guide'",
"naming": "CSS custom property names as written in the source",
"synced": "2026-11-15",
"tokens": { "--color-accent": "#2e6b57", "--radius-md": "10px" },
"components": { "Button": "drawn", "Badge": "drawn", "Input": "in code only" }
}
tokens保存的是双方在上次同步时都同意的值,仅限这些值。- 导入一个组件只会更新其自身的
components条目。
导入(代码 → 设计工具)
-
检测:使用信号文件。找到值的真实来源(令牌源文件,而非生成的输出)以及工具将使用的命名规则。如果存在两个 UI 包,则列出两者并询问哪个是来源。
-
清单,然后停止:使用清单格式:
- 按角色分类的令牌,附带数量和路径;
- 组件(当数量超过约 15 个时进行分组统计);
- 指南文档;
- 差距;
- 冲突:任何在工具中已存在且值不同的名称,以及工具无法容纳的任何令牌类型。
询问现在要绘制哪些组件,建议 3–6 个用于后续界面,并询问如何解决每个冲突。默认情况下从不绘制所有内容。
-
在工具中构建:在获得答案后执行以下操作:
- 按照命名规则注册令牌;切勿覆盖用户未解决的工具值;
- 创建一个基础指南页面,将指南文档作为图例;
- 创建一个组件索引:名称、代码路径、状态(
drawn/in code only),绘制后填充变体; - 绘制选定的组件及其状态矩阵,使用代码中的值。代码中未定义的状态将被绘制并标记为**“待定”**。
-
自我检查:渲染指南。如果代码可以渲染该组件(如 Storybook、演示页面),则在相同尺寸下进行比较。否则,说明值是从代码中读取但未渲染的。
-
记录:
- 写入
design-sync.json(所有令牌值现在双方一致,外加组件状态); - 在
DESIGN.md中,品牌团队会看到“设计系统来源:<路径>;<工具> 指南镜像它”,决策日志中会添加一条带日期的导入记录; - 如果不存在
DESIGN.md,则创建一个,其第一行为<!-- sync record only: run craft-setup for the brief -->,仅包含品牌团队信息和决策日志。craft会将没有产品部分的DESIGN.md视为缺失。
- 写入
导入单个组件(来自 craft)
用户已同意镜像系统,因此无需清单暂停步骤:
- 绘制该组件;
- 将其
components条目设置为drawn; - 保持
tokens不变。
如果工具中尚没有指南,或者用户从未同意导入(或拒绝了导入),则询问一次:“输入仅存在于代码中。是否先将其导入指南?”
导出(设计工具 → 代码)
-
读取:读取指南中的值(通过适配器)和代码中的值,按名称匹配。
-
对每个名称进行分类:使用
design-sync.json和差异格式:- 当前相等 → 同步中;
- 指南已更改 → 提议;
- 代码已更改 → 建议刷新指南;
- 两者都已更改 → 显示三个值并询问哪个胜出。
如果没有
design-sync.json,则列出所有差异并询问每个差异的处理方向。 -
提议编辑:针对源文件(而非生成的输出):文件及行号、每个编辑的影响范围、以及颜色的对比度。标记为“待定”的状态和替换的字体不属于要导出的更改。停止。
-
应用:仅应用已批准的内容,对于决定采用代码方的任何内容更新指南,然后运行项目的检查(lint、类型检查、测试、视觉测试),如果没有则说明。
-
记录:
- 更新
design-sync.json,使双方的值现在一致; - 在
DESIGN.md› 决策日志中添加一条带日期的记录; - 将未解决的冲突添加到开放问题中。
- 更新
规则
| 规则 | 原因 |
|---|---|
| 代码和工具中使用相同的名称,并遵循一个书面的命名规则 | 每个决策对应一个名称;避免因映射而产生偏差 |
design-sync.json 仅记录已同意的值 | 没有上次同意的值,“谁更改了它?”就成了猜测 |
| 绘制前先制作清单并选择;冲突在其中列出 | 大型包和已有的工具令牌需要用户决策 |
| 值来自代码,绝不来自截图 | 截图会四舍五入颜色和尺寸 |
| 缺失的状态绘制为“待定” | 指南不能声称代码具备它不具备的功能 |
| 导出时提议后停止;编辑源文件而非生成的输出 | 代码最终交付给用户;生成的文件会被下一次构建覆盖 |
| 两者都更改 → 询问 | 覆盖任一方都会丢失某人的决策 |
| 代码是真实来源,除非用户另有说明 | 符合“代码胜过陈旧的需求”原则 |
完成条件
- 导入: 清单和冲突已解决;选定的组件已绘制;指南已渲染(或注明“未渲染”);
design-sync.json和DESIGN.md已写入。 - 单个组件: 已绘制,并且其状态已更新。
- 导出: 已批准的编辑已应用;检查已运行(或注明“无”);
design-sync.json已更新;冲突已解决或标记为开放。
常见错误
| 想法 | 实际情况 |
|---|---|
| “代码已有系统,所以设置只需要需求说明” | 应主动提供导入操作,否则工具永远不会获得指南,界面会偏离代码。” |
| “我先构建基础页面和索引,组件稍后再说” | 应展示清单并询问现在要绘制哪些组件。 |
“我会在导入时将 --sand-200 重命名为角色名” | 保持代码原有的名称;将角色提议作为开放问题提出。 |
“工具中已有 --color-accent,我直接更新它” | 这是清单步骤中的冲突,不能静默覆盖。 |
| “指南和代码不一致,所以指南过时了” | 检查 design-sync.json:它可能是用户未导出的更改。 |
| “差异很小,我直接应用就行” | 必须提议、停止,然后应用并运行项目检查。 |