告别手动切图！用 Claude Code + Figma MCP 将设计稿一键生成 HTML

小婉
3 阅读12分钟

前言

作为一名前端开发者，你是否有过这样的经历：设计师丢过来一个 Figma 设计稿，你对着屏幕一点一点地量间距、取色值、调字体大小，一个页面搞下来大半天就没了。更别提反复修改时那种"改一版设计，重写一遍代码"的酸爽。

最近我摸索出了一套工作流：Claude Code + Figma MCP，直接把 Figma 设计稿转化成 HTML，还原度能做到 95% 以上。整个过程只需要配置一次，之后每次只需要把 Figma 链接丢给 AI，几分钟就能拿到可用的代码。

这篇文章就把完整的配置、实战经验和团队协作方案分享出来，希望对大家有帮助。

一、传统流程的痛点

传统的设计到开发流程大致是这样的：

设计师出图 → 手动标注 → 开发逐像素还原 → 评审 → 反复修改 → "差不多就行"

这个流程有几个致命问题：

  • 信息损耗严重：设计师的意图在层层传递中不断打折，最终实现往往只能做到"差不多"。
  • 效率极低：一个中等复杂度的页面，前端工程师手动还原需要 2-4 小时。
  • 重复劳动：设计改一版，代码就要跟着改一遍，改到怀疑人生。

而 Figma MCP 的出现，正在改变这一切。

二、什么是 MCP？为什么它能解决这个问题？

MCP（Model Context Protocol）是 Anthropic 提出的开放协议标准，用来让 AI 工具安全地连接外部服务和数据源。

用人话解释就是：MCP 相当于给 AI 装了一个"USB 接口" ，让 Claude Code、Codex 这类 AI 编程工具能直接读取 Figma 设计稿中的结构化数据——包括图层层级、颜色、字体、间距、Auto Layout 等。

AI 拿到的不是截图，而是结构化的设计信息，所以它能真正"理解"设计意图，而不是靠猜。

工作流程大概长这样：

Figma 设计稿 ──MCP──▶ AI 编程工具 ──▶ 生成 HTML/CSS/JS ──▶ 项目目录

三、环境配置（5 分钟搞定）

3.1 获取 Figma Personal Access Token

  1. 登录 Figma，点击头像进入 Settings
  2. 找到 Security → Personal access tokens
  3. 点击 Generate new token，输入名称
  4. 权限勾选：File content (read-only) 和 Current user (read-only)
  5. 复制生成的 Token（以 figd_ 开头）

3.2 安装 Figma MCP 到 Claude Code

打开终端（Terminal），执行以下命令：

claude mcp add figma -- npx -y figma-code-mcp

这条命令会把 figma-code-mcp 这个 MCP 服务器添加到 Claude Code 中。

💡 小贴士：figma-code-mcp 是目前社区最流行的方案之一，完全免费，没有调用次数限制。

3.3 配置 Token 环境变量

为了让 Claude Code 能读到你的 Figma Token，需要把它设置为环境变量。

临时生效（仅当前终端窗口）：

export FIGMA_TOKEN="你的_figma_token"

永久生效（推荐）：

把上面这行加到你的 shell 配置文件里（~/.zshrc 或 ~/.bashrc）：

bash
echo 'export FIGMA_TOKEN="你的_figma_token"' >> ~/.zshrc
source ~/.zshrc

3.4 验证连接

完全关闭 Claude Code 再重新打开，然后在对话框里输入：

/mcp

如果看到 figma 状态显示为 ✔ connected，说明配置成功了。

四、进阶：创建专属 Agent（Skill）

MCP 只是打通了数据通道，但 AI 怎么生成代码、生成什么风格的代码，还需要我们给它设定规则。

4.1 从 instructions.md 到 Skill

Claude Code 支持两种方式来定制 AI 行为：

方式特点适用场景
instructions.md自动加载，常驻上下文通用规则，每个任务都需遵守
Skill按需加载，节省 Token特定任务的 SOP，可复用可共享

对于"Figma 转 HTML"这个高频场景，Skill 是更好的选择。

4.2 创建 Figma-to-HTML Skill

在项目根目录下创建 .claude/skills/figma-to-html/SKILL.md 文件，内容如下：

---
---
name: figma-to-html
description: 将 Figma 设计稿节点转换为可直接运行的 HTML/CSS/JS 代码。当用户提供 Figma 链接并希望生成页面代码时，应自动调用此 Skill。
---

# Role: Figma-to-HTML 专用实现 Agent

你是一名资深前端工程师，专精于像素级还原 Figma 设计稿，并生成可直接运行的高质量 HTML 代码。当用户提供 Figma 链接或要求生成 HTML 时，你必须严格遵循以下工作流（SOP）。

---

## 🚨 核心原则（优先级最高）

1. **所有文本内容必须以 HTML 文本节点（`<p>`, `<span>`, `<h1>`~`<h6>`, `<label>` 等）输出，严禁将任何文本图层转换为图片。** 这是铁律，违反此规则视为任务失败。
2. **生成代码必须可直接在浏览器中打开运行**，无需任何外部依赖（CDN 库除外）。
3. **移动端优先**：默认生成响应式页面，适配 375px ~ 1920px 屏幕宽度。

---

## 1. 信息提取 (Parse Inputs)

- 当用户提供 Figma 链接时，自动解析出 `FILE_KEY` 和 `NODE_ID`。
  - _规则_：链接中 `file/` 后面的字母数字串是 `FILE_KEY`；`?node-id=` 或 `?node-id%3D` 后面的部分是 `NODE_ID`（注意将横杠 `-` 转为冒号 `:`，如 `1-2` -> `1:2`）。
  - _示例_：`https://www.figma.com/design/abc123/MyDesign?node-id=1-2` → `FILE_KEY=abc123`, `NODE_ID=1:2`
- 如果链接中包含多个 `node-id`（如 `1-2,3-4`），默认只处理第一个，同时询问用户是否需要处理全部。
- 如果用户只提供 Node ID 或 File Key 其中之一，主动询问补齐缺失信息。

---

## 2. 调用 MCP 工具获取设计稿 (Fetch Design)

你必须按顺序调用 Figma MCP 的 Tools：

- **第一步（获取结构数据）**：调用工具获取设计稿的完整节点树和样式属性（包括但不限于：尺寸、颜色、字体族、字号、行高、字重、间距、圆角、阴影、边框、透明度、Auto Layout 属性等）。
- **第二步（获取视觉截图）**：调用工具获取该节点的 Base64 截图，用于生成代码后的视觉比对（仅用于参考，不作为代码生成的直接数据源，以避免"文本转图片"的歧义）。

⚠️ **数据优先级**：以第一步的结构数据为准，截图仅用于人工核对视觉效果。

---

## 3. 代码生成策略 (Code Generation)

基于获取到的结构化数据，生成单一的 `index.html` 文件，包含内联 CSS 和 JavaScript。

### 3.1 HTML 结构

- 使用语义化标签（`<header>`, `<main>`, `<section>`, `<article>`, `<nav>`, `<footer>` 等）。
- **所有文本内容必须从 Figma 数据中提取并写入 HTML 标签内，不得用图片替代。**
- **图片资源处理（按优先级）**：
  1. **优先**：如果 MCP 支持图片导出，使用导出的真实图片。
  2. **其次**：从设计稿中提取 `imageRef`，通过 Figma API 生成可访问的图片 URL。
  3. **兜底**：使用 `picsum.photos` 占位图，但必须在 HTML 中用 `<!-- TODO: 替换为真实图片 -->` 注释标注。
  4. **禁止**：不要将文本内容转为图片（这是铁律）。
- **图标处理**：优先使用 SVG 内联或 Unicode 符号，其次使用 Font Awesome 等免费图标库。

### 3.2 CSS 样式

- **布局**：使用 Flexbox 或 Grid 布局，精确还原设计稿的间距（`margin`/`padding`）、对齐方式。
- **颜色**：从设计稿中提取十六进制色值或 RGBA 值，不得近似猜测。
- **字体**：
  - 从设计稿中提取 `font-family`，优先使用 Google Fonts 或系统字体栈。
  - 如果设计稿使用了特殊字体，自动在 `<head>` 中添加 Google Fonts CDN 链接。
  - 字体大小、行高、字重必须与设计稿一致（单位使用 `px` 或 `rem`）。
- **响应式**：
  - 默认使用相对单位（`%`, `vw`, `vh`, `rem`, `em`）和 `clamp()` 函数实现流畅缩放。
  - 在关键断点（如 768px, 1024px）使用 `@media` 查询调整布局。
- **交互反馈**：为按钮、链接等可交互元素添加 `:hover`、`:active`、`:focus` 样式。

### 3.3 JavaScript 交互

- 由于 Figma 是静态设计稿，你需要根据常见的 UI 模式**智能生成**合理的交互逻辑。
- **常见交互模式**（根据设计稿自动判断是否包含）：
  - 导航菜单（移动端汉堡菜单切换）
  - Tab 切换 / 手风琴折叠
  - 轮播图 / 图片滑动
  - 表单验证（邮件格式、必填项等）
  - 按钮点击反馈（弹窗、页面跳转模拟、数据提交模拟）
  - 滚动动画（滚动到指定位置、淡入效果等）
- 如果用户有明确的交互需求，以用户描述为准，覆盖自动判断的逻辑。

---

## 4. 输出与交付 (Delivery)

- **第一步**：在对话中直接输出完整的 `index.html` 代码（代码块内）。
- **第二步**：使用 `write_to_file` 工具将代码保存为项目根目录下的 `index.html` 文件。
- **第三步**：如果环境支持（如 Claude Code 内嵌浏览器或 Playwright MCP），自动打开预览并提示用户查看。
- **第四步**：生成后，主动告知用户：
  - 已保存的文件路径
  - 如何打开预览（如“在浏览器中打开 index.html”）
  - 交互功能说明（列出了哪些交互效果）

---

## 5. 设计变量提取 (Design Tokens)

在生成代码前，从设计稿中提取并整理以下设计变量，便于代码维护：

```css
/* 示例结构，实际变量从设计稿中提取 */
:root {
  --color-primary: #...;
  --color-secondary: #...;
  --color-background: #...;
  --font-family-base: '...', sans-serif;
  --font-size-heading: ...px;
  --font-size-body: ...px;
  --spacing-unit: ...px;
  --border-radius: ...px;
  --shadow-default: ...;
}


### 4.3 如何使用

配置完成后，使用极其简单：

**方式一：自动触发**  
只要你在对话中提到"Figma"、"设计稿转 HTML"等关键词，Claude 会自动加载这个 Skill。

**方式二：手动调用**  
在对话框里输入 `/figma-to-html`，强制激活该 Skill。

**示例指令**：



```text
根据这个设计稿生成 HTML：https://www.figma.com/design/abc123/MyDesign?node-id=1-2

五、避坑指南

5.1 文本被转成图片了怎么办？

这是常见问题——为了确保视觉一致性，AI 有时会把复杂文本图层导出为图片。

解决方案：在 SKILL.md 中用铁律明确禁止。就像上面规则里写的那样——"所有文本内容必须以 HTML 文本节点输出，严禁将任何文本图层转换为图片。"

5.2 图片资源变成了占位图？

AI 无法直接读取 Figma 中的图片二进制数据，所以会使用 picsum.photos 等占位图服务。

解决方案：

  1. 在 Skill 规则中增加"图片资源处理"优先级指引
  2. 尝试使用支持图片导出的 MCP 模式（如 --image 参数）
  3. 关键图片手动导出后，在提示词中告诉 AI 使用本地图片

5.3 交互逻辑怎么来？

Figma 是静态设计工具，原型中的交互动效无法被 MCP 读取。

解决方案：在 Skill 中预设常见的交互模式（Tab 切换、轮播图、表单验证等），让 AI 根据设计稿自动判断该生成哪些交互。

5.4 在 Codex 桌面版中使用

如果你用的是 Codex 桌面版而不是 Claude Code，配置方式略有不同：

特性Claude CodeCodex 桌面版
项目级指令.claude/instructions.mdAGENTS.md
Skill 目录.claude/skills/.codex/skills/ 或 ~/.codex/skills/
MCP 配置claude mcp add ...通过 ~/.codex/config.toml 配置

你可以把为 Claude Code 准备的 Skill 直接复制到 Codex 对应的目录下使用。

六、多项目与团队共享方案

当你在多个项目中使用这个 Skill，或者需要和团队成员共享时，有几种方案可选：

6.1 全局 Skills 目录（个人开发者最推荐）

Claude Code 支持在用户目录下设置全局 Skills 文件夹，所有项目都能自动访问。

# 创建全局 Skill 目录
mkdir -p ~/.claude/skills/figma-to-html

# 复制 Skill 文件到全局
cp -r 当前项目/.claude/skills/figma-to-html/* ~/.claude/skills/figma-to-html/

配置后，所有项目都能使用这个 Skill。项目级 Skill 会覆盖全局同名 Skill，方便在特定项目里做定制。

6.2 符号链接（统一管理）

如果你想把 Skill 统一放在一个地方管理（比如一个 Git 仓库），然后用软链接挂载到各个项目里。

# 创建集中的 Skill 仓库
mkdir -p ~/my-skills/figma-to-html

# 在项目里创建软链接
cd 你的项目根目录
mkdir -p .claude/skills
ln -s ~/my-skills/figma-to-html .claude/skills/figma-to-html

6.3 Git Submodule（团队共享）

适合团队内统一版本管理：

# 创建 Skill 仓库并添加到项目中
git submodule add https://github.com/your-team/claude-skills.git .claude/skills

# 团队成员拉取
git clone --recursive 你的项目地址
# 或
git submodule update --init --recursive

6.4 方案对比

方案适用场景优点缺点
全局 Skills个人开发者一次配置，所有项目生效项目间无法独立定制
符号链接统一管理 Skill 源码更新一处，全局同步团队协作需各自配置
Git Submodule团队协作版本统一，可追溯配置较复杂
项目模板频繁新建项目开箱即用，可独立修改更新模板需手动维护

6.5 Codex 桌面版的全局配置

如果你主要使用 Codex 桌面版，全局配置方式类似：

# Codex 全局 Skill 目录
mkdir -p ~/.codex/skills/figma-to-html
cp -r 当前项目/.claude/skills/figma-to-html/* ~/.codex/skills/figma-to-html/

或者通过配置文件 ~/.codex/config.toml 指定：

[skills]
paths = ["~/.codex/skills", "~/my-skills"]

七、效果与思考

这套方案我实际跑了一段时间，几点感受：

效率提升是质变的。以前一个中等页面手动还原需要 2-4 小时，现在几分钟就能拿到初版代码，剩下的时间只需要做微调和业务逻辑。

代码质量更一致。因为 AI 直接从设计系统中提取颜色、间距、字体等 Design Token，不会出现"开发者理解偏差"导致的不一致问题。

迭代更快了。设计改版？直接把新链接丢给 AI，重新生成一份就行，不用再从头改一遍。

当然它也不是万能的。复杂的自定义交互、特殊的动画效果还是需要人工介入。但作为一个"设计稿转代码"的起点，这套方案已经能帮我们省掉 80% 以上的重复劳动了。

八、结语

技术的本质是让人从重复劳动中解放出来。Figma MCP + AI 编程工具这套组合，让我们离"设计稿即代码"又近了一步。

配置一次，终身受益。无论是个人开发者还是团队协作，都能找到适合自己的共享方案。赶紧去试试吧！

如果你在配置过程中遇到问题，欢迎在评论区交流讨论。

avatar
文章
阅读
粉丝