这套工作流能做出什么
照着做完，你会得到一条从"设计规范"到"上线交付"的自动化链路：
- 设计系统文件里的颜色、间距、圆角、字号全部用变量承载，组件与变体命名统一，Agent 能按名字精确取用，而不是靠猜；
- 用一段自然语言描述需求，Agent 在 Figma 里用已有的组件和变量拼出界面草稿；
- 改稿时 Agent 只动指定画板，并输出"改了哪些节点、依据哪条规范"的说明，方便评审；
- 交付前 Agent 跑一遍检查清单，把硬编码色值、缺失变量、未映射组件等问题列成清单，附在评审或交付说明里。
核心思路只有一句：把设计规范从一份 PDF 变成 Agent 能执行的结构化约束。规范越像"数据"，Agent 越稳定；规范越像"散文"，Agent 越容易自由发挥。
前置条件
开始前确认这几件事：
1. Figma 权限：能访问目标团队与项目，具备创建设计系统文件的权限。若要读写变量（Variables），需要对应的付费席位与团队权限，具体以官方页面为准。
2. 个人访问令牌：在 Figma 账号设置中生成 Personal Access AI 词典：Token">Token，只勾选需要的 scope（读文件、读变量即可起步）。
3. 一个支持 MCP 的智能体客户端，或能发起 HTTP 请求的脚本环境。Figma 提供 MCP 服务，具体名称、安装方式与地址以官方文档当前版本为准。
4. 本地环境：Node.js（若走本地 MCP 服务）、jq 和 curl（用于调试 API）。
5. 一个用来存放提示词与规则的仓库，例如 design-agent/ 目录，里面放规则文件和检查脚本。
安全提醒：令牌只放环境变量或密钥管理服务，不要写进仓库、不要贴进聊天记录。
第一步：把设计系统做成"机器可读"的事实源
Agent 读不懂设计意图，但读得懂名字。所以先把命名收敛。
变量分层命名。建议三层：类别/子类/状态。例如颜色用 color/text/default、color/text/muted、color/bg/surface；间距用 space/100、space/200；圆角用 radius/sm、radius/md。
组件命名。用 组件名/变体维度=值 的形式，例如 Button/Primary、Button/Secondary、Card/Product。
给变量和组件写描述。Figma 的描述字段 Agent 能读到，这是成本很低的"内嵌文档"。写清楚"什么时候用它"，比写"它是什么颜色"有用得多。
页面结构固定下来，例如：
```text
00 Cover
01 Foundations ← 变量、文本样式、效果样式
02 Components ← 组件与变体
03 Patterns ← 常见组合（表单、空状态、列表项）
04 Screens ← 真实页面，Agent 主要在这里工作
99 Sandbox ← Agent 试验区，随便改
```
把规则写成一份文件放进仓库，让 Agent 每次开工先读：
```markdown
design-rules.md
命名约定
- 颜色变量：color/{用途}/{层级}，例如 color/text/default
- 间距变量：space/{档位}，只允许使用 space/100 ~ space/800
- 组件命名：{组件名}/{变体维度}={值}
硬性约束
- 禁止使用十六进制色值，一律引用变量
- 禁止修改 02 Components 下的组件主件
- 新增界面只能放在 04 Screens 下，命名格式：{需求编号}-{页面名}
- 只用 02 Components 里已存在的组件；找不到时先在输出里说明，等待确认
输出格式
每次改稿输出：变更节点列表、使用的变量清单、不确定项
```
第二步：把 Figma 接到智能体
有两种接法，按团队情况选。
接法 A：MCP 服务（适合交互式改稿）
在智能体客户端里配置 MCP 服务，让 Agent 具备读取设计上下文的能力：
```json
{
"mcpServers": {
"figma": {
"command": "<按官方文档填写启动命令>",
"args": ["<按官方文档填写参数>"],
"env": {
"FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"
}
}
}
}
```
字段名与启动方式会随官方实现变化，以官方文档当前版本为准。配置好后，先让 Agent 做一次只读操作，确认它能列出文件里的页面名。
接法 B：REST API（适合脚本化、批处理）
先验证令牌可用：
```bash
export FIGMA_TOKEN="你的令牌"
export FILE_KEY="设计系统文件 key"
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
"https://api.figma.com/v1/files/$FILE_KEY?depth=2" \
| jq -r '.document.children[].name'
```
预期输出就是前面那套页面名。批量导出变量、生成变量对照表时，这条路更顺手：
```bash
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
"https://api.figma.com/v1/files/$FILE_KEY/variables/local" \
| jq '.meta.variables | to_entries[] | {name: .value.name, type: .value.resolvedType}'
```
变量接口的可用范围与权限要求随账号类型不同，若返回权限错误，先确认席位与 scope。
第三步：定义三种任务模式
不要让 Agent"随便帮我设计一下"，而是给它明确的模式。把下面三段模板存成文件，按需调用。
模式一：生成界面
```text
角色：你按 design-rules.md 在 Figma 里搭建界面。
输入：需求描述如下 ——
{粘贴需求，例如"商品详情页需要一块优惠券区域，含标题、两张券卡片、一个查看更多链接"}
步骤：
1. 先列出你打算使用的组件与变量，不要立刻动手；
2. 我确认后，在 04 Screens 下新建画板，命名为 {需求编号}-商品详情-优惠券；
3. 只用 02 Components 里的组件，间距只用 space 变量；
4. 输出：使用的组件清单、变量清单、未能覆盖的需求点。
```
模式二：改稿
```text
角色：你只做最小改动。
输入：目标画板 {画板名}，修改要求 {例如"卡片间距从 space/300 改为 space/400，按钮换成 Secondary"}；
约束：
- 只修改该画板内的节点，不触碰其他画板；
- 不修改任何组件主件；
- 若要求与 design-rules.md 冲突，先停下来说明冲突点，不要自作主张。
输出：变更节点列表（节点名 + 改动前后），以及这次改动是否引入新变量。
```
模式三：交付检查
```text
角色：你是交付前检查器，只读不写。
逐项检查目标画板，输出 Markdown 表格：
| 检查项 | 结果 | 位置 | 建议 |
检查项：
1. 是否存在硬编码十六进制色值
2. 是否使用了 design-rules.md 之外的颜色或间距值
3. 是否使用了非 02 Components 来源的组件实例
4. 文本样式是否来自 01 Foundations
5. 画板命名是否符合 {需求编号}-{页面名}
6. 是否可以映射到代码组件（若已配置组件与代码的对应关系）
```
第四步：让改稿可控
Agent 改稿出问题，多半是因为"一次让它改太多"。三条实操建议：
先读后写。任何写操作前，要求 Agent 先输出变更清单，人工确认再执行。这一步能挡掉大部分误改。
限定作用域。把任务范围写死到具体画板名，并明确"不要动组件主件"。组件主件一旦被改，所有引用它的地方都会跟着变，排查成本很高。
要求 diff 说明。让 Agent 输出"节点名 + 改动前 + 改动后"，这份说明直接贴进评审卡，评审人不用逐个图层点开看。
如果团队用 Git 管理代码，可以顺手加一条：Agent 输出的变量清单，与代码侧的 token 文件做一次比对，差异项在评审里标出来。
第五步：接入评审与交付
把 Agent 的输出接进现有流程，而不是另起一套：
评审阶段。提交 Figma 链接时，同时附上 Agent 生成的变更说明和检查表格。评审人关注三件事：改了什么、为什么这么改、有没有破坏规范。
交付阶段。准备一份固定清单，每次交付走一遍：
```markdown
- [ ] 画板命名符合规范，位于 04 Screens 下
- [ ] 无硬编码色值，全部引用变量
- [ ] 使用的组件均来自 02 Components
- [ ] 新增变量已补充描述字段
- [ ] 组件与代码的对应关系已更新（如已使用该能力）
- [ ] Agent 检查表已附在交付说明中
- [ ] 不确定项已列出并指派负责人
```
沉淀阶段。把这次踩到的坑补进 design-rules.md。规则文件是活的资产，每补一条，下次 Agent 的返工就少一次。
常见坑与排错
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 连接失败或 401 | 令牌失效、scope 不足、环境变量未生效 | 重新生成令牌，确认 echo $FIGMA_TOKEN 有值 |
| Agent 说"找不到某组件" | 组件名拼写不一致，或组件在别的文件里 | 先导出组件名清单，人工核对命名 |
| 返回内容过大、上下文被撑满 | 一次读取整个文件 | 加 depth 参数，或按页面、按画板分批读取 |
| 改稿波及无关页面 | 未限定作用域，或误改组件主件 | 在提示词里写死画板名；改动后检查组件主件是否被动过 |
| 生成了不存在的变量 | 模型按命名规律"推测"了一个变量 | 第一步先让它列可用变量清单，确认后再用 |
| 每次输出格式都不一样 | 规则文件太笼统 | 在 design-rules.md 里固定输出模板 |
| 变量接口报权限错误 | 席位或 scope 不支持 | 检查账号权限，改为手动导出变量表 |
一条通用排错思路：把 Agent 当成刚入职的同事。它出错时先问"我有没有把规则讲清楚"，再怀疑工具本身。
下一步建议
1. 从小范围试点。挑一个模块、一个页面跑通全流程，别一上来就全量铺开。
2. 先整理设计系统，再接 Agent。命名混乱时接 Agent，只会把混乱放大。
3. 把提示词当代码管。规则文件进仓库、走评审、留版本，改动有记录。
4. 加一层自动化检查。把交付清单里的可判定项写成脚本，在 CI 里跑，人工只看结论。
5. 定期回看规则文件。每季度清理一次过时条目，保持规范与实际用法一致。
工具能力在快速演进，涉及具体接口、字段名和权限范围的地方，动手前先看一眼官方文档的当前版本，比照着旧文章抄要省事得多。