Zack Figma To Code

---
name: zack-figma-to-code
description: "把 Figma 设计稿转成生产代码：Figma MCP 的取数与顺序、节点选择、令牌映射、翻译成项目既有约定、1:1 还原验收与差异定位。当用户给出 Figma 链接或 node-id、设计稿截图，要求实现设计、还原稿子、或抱怨「还原得不像」时使用。同时覆盖 Figma MCP 的连接与排错。"
license: MIT
metadata:
  author: Zack
  homepage: https://github.com/yckonnnnn/zack-design-skills
  version: "1.0.0"
---

# 设计稿 → 生产代码

### 令牌与设计稿冲突时，谁赢

这是还原工作里最容易含糊、也最容易扯皮的一条。**分维度定优先级，不要笼统地喊「1:1 还原」：**

| 维度 | 谁赢 | 说明 |
|---|---|---|
| 颜色 | **项目令牌** | 设计稿的十六进制映射到令牌；如果令牌里没有对应值，报出来新增，不要硬编码 |
| 字体族 | **项目令牌** | 设计稿用的字体没授权就换，并明确告知 |
| 字号 / 间距尺度 | **项目令牌**，差异需上报 | 设计稿 13px 而尺度里只有 12/16 → 报给设计师，不要静默取整 |
| 布局几何（位置、对齐、结构） | **设计稿** | 这是设计的本体，不要按自己的审美改 |
| 圆角 | **设计稿** | 除非项目有强制的形状语言（例如全站只允许 0px） |
| 交互状态 | **项目规范** | 设计稿通常没给，按第三节补齐 |
| 组件边界 | **项目既有组件** | 设计稿画成一个整块，但项目里已有能拼出的组件 → 复用 |

**一句话：颜色和尺度听代码库，布局几何听设计稿，两者的差值记进验收报告。**

**总原则**：设计稿给的是「长什么样」，项目给的是「怎么组织」。**前者服从设计稿，后者服从代码库。**

最常见的失败是两件事同时发生：模型把 MCP 生成的 React + Tailwind 直接粘进一个 Vue + CSS Modules 的项目，同时凭记忆目测间距。结果是既不还原、也不符合项目约定。

---

## 一、取数顺序（不许跳步）

| 步 | 动作 | 为什么 |
|---|---|---|
| 1 | **确认节点。** 从链接里取 `fileKey` 与 `node-id`（形如 `node-id=1-2`）。桌面端可直接选中图层。 | 节点错了后面全错 |
| 2 | `get_design_context` | 拿到结构化设计数据 + 默认代码。这是主数据源 |
| 3 | 响应过大或被截断 → `get_metadata` | 拿到稀疏的图层树（id / 名称 / 类型 / 位置 / 尺寸），再只对需要的子节点重取 `get_design_context` |
| 4 | `get_variable_defs` | 拿到设计变量（颜色 / 间距 / 字体），用于映射到项目令牌。**这一步最常被跳过，也是「看起来像但不对」的根因** |
| 5 | `get_screenshot` | 视觉基准。必须拿到，否则无法验收 |
| 6 | `get_code_connect_map`（若有 Code Connect） | 拿到「Figma 节点 → 项目组件」的映射，优先复用既有组件而不是重造 |
| 7 | 下载/导出资源 | 图标导出为 SVG，图片按 @2x 或按实际显示尺寸 |
| 8 | **写代码** | 翻译成项目约定（见第二节） |
| 9 | **1:1 验收** | 截图对比 + 尺寸核对（见第四节） |

**前置检查**：如果 MCP 无响应，先确认连接（见 [`references/figma-mcp-setup.md`](references/figma-mcp-setup.md)），不要靠「照着截图猜」硬做——猜出来的偏差会全部变成返工。

### 远程 vs 桌面

- **远程服务器**：基于链接。复制 frame / layer 的链接给 MCP，客户端从链接里解析 node id（它不会去浏览页面）。
- **桌面（Dev Mode）**：基于选中。可以直接选中图层提问，不需要链接。

---

## 二、翻译成项目约定（这一步才叫「实现」）

MCP 吐出来的默认代码是**参考**，不是成品。逐项翻译：

| MCP 输出 | 你要做的 |
|---|---|
| React + Tailwind | 转成项目框架（Vue / Svelte / SwiftUI / 原生 HTML+CSS…） |
| Figma 变量名 | 映射到项目令牌。**找不到对应令牌就新增，不要硬编码十六进制** |
| 绝对定位的图层 | 改成正常文档流 / Flex / Grid。设计稿的绝对坐标是实现细节，不是布局方案 |
| 内联样式 | 抽成 class / 组件 props |
| 硬编码文案 | 抽成 i18n key 或 props |
| 单个大块 JSX | 按设计稿的图层结构拆成组件 |
| 哑组件 | 补齐 props、状态、事件（设计稿通常只有静态态） |
| 默认间距值 | 对齐项目的间距尺度；如果设计稿的值不在尺度里，**先跟设计师确认**，不要自己改 |

### 令牌映射表（写代码前先填）

```
设计变量            →  项目令牌
color/bg/primary    →  --color-surface-1
color/text/default  →  --color-text-primary
spacing/4           →  --space-4
radius/md           →  --radius-md
text/heading-lg     →  --step-3
```

**发现设计变量和项目令牌对不上时，报出来。** 「设计稿用了 13px 的间距，项目尺度里没有 13」是有价值的信息，不是要你偷偷取整。

### 复用优先

1. 项目里已经有对应组件 → **复用**，不要新建。
2. 差一点点 → 加一个 variant / prop，不要 fork 出第二份。
3. 确实没有 → 新建，放在项目既有的组件目录里，命名跟随既有风格。

---

## 三、还原精度

设计稿里**必须**严格对齐的：

- 字号、字重、行高、字距
- 颜色（用令牌，不用吸管取色）
- 间距（内边距、元素间距）
- 圆角
- 图标尺寸与线宽
- 元素对齐关系

设计稿里**允许**你自己决定的（这些是设计稿的空白，不是遗漏）：

- 悬停 / 聚焦 / 按下 / 禁用状态（除非稿里有）
- 空状态、加载态、错误态
- 响应式行为（设计稿通常只给了 1–2 个宽度）
- 长文本溢出策略
- 键盘操作与焦点顺序
- 动画曲线与时长

**遇到设计稿明显不合理的地方**（对比度不足、点击区 < 44px、12px 正文、色盲不可辨的状态色）：**实现符合规范的那一版，并明确告诉用户你偏离了哪里、为什么。** 不要沉默地照抄，也不要沉默地改掉。

---

## 四、1:1 验收（不跑这一步等于没做）

```
1. 在相同宽度下截图（设计稿导出 + 实际渲染），宽度必须一致，否则一切对比无意义
2. 叠图对比（50% 透明度）或用像素 diff
3. 逐项量：边距、字号、行高、色值
4. 只看差异 > 2px 或色差 ΔE > 2 的位置
5. 修正后重新截图，直到差异只剩抗锯齿
```

推荐同时看三个宽度：**1440 / 1024 / 390**。设计稿通常只给一个，另外两个是你补的，要确认补得合理而不是硬挤。

### 用 Playwright 量而不是用眼睛估

```python
# 逐个关键元素读实际盒模型，跟设计稿数值对照
page.set_viewport_size({"width": 1440, "height": 900})
el = page.query_selector(".hero-title")
box = el.bounding_box()
computed = page.evaluate("""el => {
  const s = getComputedStyle(el);
  return { fontSize: s.fontSize, lineHeight: s.lineHeight,
           letterSpacing: s.letterSpacing, color: s.color,
           fontFamily: s.fontFamily };
}""", el)
print(box, computed)
```

**不要凭截图目测间距。** 目测的误差是 4–8px，肉眼看不出来但并排一看就歪。

### 验收报告

```
## 还原验收
| 项 | 设计稿 | 实现 | 差异 | 处理 |
|---|---|---|---|---|
| 标题字号 | 48px | 48px | 0 | — |
| 标题字距 | -1.44px | 0 | 1.44px | 已补 letter-spacing: -0.03em |
| 卡片内边距 | 24px | 32px | 8px | 项目 --space-6=32，已与设计师确认采用 32 |

宽度：1440 / 1024 / 390
未验收：iframe 内滚动行为、Safari 下的字体回退
```

---

## 五、常见偏差与原因

| 症状 | 根因 | 修法 |
|---|---|---|
| 整体「像但不对」 | 只取了 `get_design_context`，没取 `get_variable_defs` | 补取变量并映射令牌 |
| 字体不对 | 设计稿用的字体项目没有 | 报出来，或找最接近的授权替代并说明 |
| 间距有 1–3px 偏差 | 设计稿用了非尺度值 | 与设计师确认，不要静默取整 |
| 大屏正常小屏崩 | 用绝对定位还原 | 改成 Flex/Grid + 流体尺寸 |
| 颜色在不同屏幕不一致 | 用了 sRGB 十六进制但设计稿是 P3 | 用 `color(display-p3 …)` 或统一色彩空间 |
| 图标糊 | 导出了 PNG 或尺寸不对 | 导出 SVG，或按 @2x/@3x 导出位图 |
| 悬停/聚焦完全没有 | 设计稿没给，就真没做 | 状态必须补（见第三节） |
| 点不动、键盘不可用 | 用 `div` 拼的交互元素 | 用语义元素；必要时补 `role` / `tabindex` / 键盘处理 |

---

## 六、自检

- [ ] 取数顺序走完，`get_variable_defs` 和 `get_screenshot` 都拿到了吗？
- [ ] 令牌映射表填了吗？有没有残留硬编码色值？
- [ ] 复用了项目既有组件吗？还是又造了一份？
- [ ] 交付的是项目框架的代码，还是 MCP 默认的 React+Tailwind？
- [ ] 状态补齐了吗（hover / focus-visible / disabled / loading / empty / error）？
- [ ] 三个宽度都看过了吗？
- [ ] 验收报告里的每一项都有实际读到的数值支撑吗？
- [ ] 偏离设计稿的地方，有没有明确告知用户？