Claude Code + Figma MCP：设计稿直出HTML的实战指南

设计师丢过来一张图前端对着标注量边距、导位图、抠图标、写一版 HTML然后设计师说“间距再小一点”“按钮换个颜色”于是全流程再来一遍。这套动作听起来很基础但它恰恰是团队里最耗时间、最容易被低估的重复劳动。我花了小半个月把 Claude Code 和 Figma MCP 串成一条“设计稿直出 HTML”的流水线之后最大的感受不是 AI 多聪明而是我终于能把精力从“对齐像素”里抽出来留给真正需要人判断的事。这篇就把我的完整搭建过程、使用姿势和踩过的坑全部写出来希望能帮你少走点弯路。1. 从手动切图到“一句话出页面”这套组合到底解决了什么1.1 传统设计稿交付流程到底累在哪很多前端刚接手设计稿时都有这种感觉设计稿本身没什么看不懂的但把设计稿变成 HTML 的过程全是琐碎活。我简单列一下传统流程里必须做的工作把位图图标从 Figma 里导出成 PNG或者复制 SVG path。手动量间距、量圆角、量字体大小、量行高、量阴影参数。把颜色、字号整理成 Sass 变量或 CSS 变量。按 Frame 层级手动切出区块再照着画 HTML 结构。写完 CSS 后截图回给设计师对比还原度往往要来回改上三四轮。设计稿更新一版后重复以上所有步骤。单个设计稿还好一旦页面多、版本频繁更新这套流程会吃掉大量时间而且还原度纯靠人的细心程度兜底。1.2 Claude Code 和 Figma MCP 分别扮演什么角色要理解这套方案先搞清楚两个角色的分工。Claude Code 是 Anthropic 推出的命令行 AI 编程工具。它和你熟悉的 Copilot 类工具有点区别它跑在终端里能直接读你本地的代码文件、执行命令、创建文件、修改目录也能调用外部工具。简单说它是一个“住在你项目里的 AI 开发助手”。Figma MCP 则是 Figma 官方提供的 MCPModel Context Protocol服务器。MCP 是一个让 AI 模型与外部数据源对接的标准化协议。你可以把它理解成给 AI 配了一根通用数据线Claude Code 原本只能看到本地文件通过 MCP 这根“数据线”连上 Figma 之后就能直接读取 Figma 云端设计稿的结构化数据包括页面布局、节点信息、颜色、字体、填充、阴影、自动布局参数等。所以这套组合的本质是Claude Code 负责“读数据、想方案、写代码”Figma MCP 负责“替它打开设计稿、把设计稿翻译成结构化信息”。两者配合起来才能做到你给一个 Figma 链接它就能生成一版结构合理、样式贴合的 HTML 页面。1.3 这套方案适合谁、不适合谁先说适合谁被 UI 还原度反复折磨的前端工程师。它能帮你把初版代码直接拉到“七成还原度”剩下三成做人工精修效率完全不在一个量级。需要快速验证页面效果的独立开发者和全栈工程师。原型阶段不用等完整设计稿草图级别的 Frame 也能直接变成可点击的 HTML。团队里负责设计交付规范的“设计工程化”角色可以把这套流程固化成团队的提效工具。再说边界。如果你的设计稿是纯视觉创意型页面比如超强动效的营销落地页、大量手绘插画和特殊图形组合的场景AI 生成的结果只能算“骨架”动效和细节还需要大量人工代码补齐。另外Figma 里的复杂组件嵌套、设计变量系统、原型交互连线这些内容MCP 目前并不能把所有信息都读出来所以别指望它能完美处理极度复杂的组件化设计系统。2. 环境搭建从安装 Claude Code 到绑定 Figma MCP 的全流程2.1 安装 Claude Code一行 npm 命令但有几个细节Claude Code 的安装本身不复杂前提是你的机器上有 Node.js 18 和 npm 9。我建议先确认一下版本node -v npm -v版本没问题的话直接全局安装npm install -g anthropic-ai/claude-code安装完成后先跑一下claude --version确认装成功再运行claude打开交互界面。首次运行会让你登录 Claude 账号。这里有个容易让新人卡住的点登录是在浏览器里完成的终端会显示一个等待授权的状态等浏览器里确认授权后回到终端继续操作即可。Windows 用户如果装了 Git Bash 或 PowerShell我实测 PowerShell 里跑 Claude Code 的兼容性最稳。Ubuntu 等 Linux 环境要注意 npm 全局安装路径是否在PATH里如果提示找不到claude命令需要把 npm 的全局 bin 目录配置到环境变量里。2.2 获取 Figma API Key权限不选对后面全是坑Figma MCP 需要用你自己的 Figma API Token 去读设计稿数据。拿 Token 的位置在Figma 头像菜单 - Settings - Security - Personal Access Tokens - Generate new token。生成时有几个关键事项一定要认真看权限选择上至少要勾选File content: read-only这个权限否则后面 MCP 调用时会一直报 403。Token 只会完整显示一次关掉弹窗之后就看不到了所以生成后要立刻复制到一个安全的地方保存。Token 相当于你 Figma 账号的钥匙不要提交到 Git 仓库里也不要随手贴在聊天工具里。拿到 Token 之后下一步就是把它交给 MCP 服务器。2.3 把 Figma MCP 注册给 Claude CodeFigma 官方维护的 MCP 服务器包名是figma-developer-mcp通过 npx 就能运行。把它注册到 Claude Code 有两种方式。方式一是通过claude mcp add命令。把下面命令里的YOUR_FIGMA_API_KEY换成你上一步拿到的 Tokenclaude mcp add figma -- npx figma-developer-mcp --figma-api-keyYOUR_FIGMA_API_KEY方式二是手动配置项目级或用户级配置文件。在项目根目录创建.mcp.json内容如下{ mcpServers: { figma: { command: npx, args: [figma-developer-mcp, --figma-api-keyYOUR_FIGMA_API_KEY] } } }我个人的建议是单机单人使用用claude mcp add最省事团队统一配置则用.mcp.json这样新同事 clone 项目后只要补上自己的 Token 就能用。2.4 验证配置是否成功先让它读一个文件试试配置完成后重启 Claude Code 让 MCP 配置生效。先在终端输入claude mcp list确认 figma 这个 server 在列表里且状态正常。然后随便打开一个 Figma 设计稿复制它的分享链接在 Claude Code 里输入一段最简单的指令请读取这个 Figma 链接的文件信息告诉我里面有哪些页面每个页面大概包含哪些模块https://www.figma.com/design/xxxxxxxx/xxx?node-id0-1如果 Claude Code 能返回类似“该文件包含 3 个页面首页有导航栏、Hero、功能列表、页脚”这样的结构描述说明 MCP 链路已经通了。到这一步环境搭建就算完成接下来可以进入真正的实战。3. Figma MCP 的工作原理它从设计稿里读来了什么3.1 MCP 协议不是新框架就是 AI 的标准化适配线很多前端第一次接触 MCP 时会觉得是又一个大而全的框架其实它没那么玄乎。你可以把 MCP 类比成 AI 世界里的 USB-C 接口标准Claude Code 支持了 MCP就相当于设备有了一个标准接口任何提供 MCP 服务的服务器比如 Figma、数据库、浏览器工具插上都能被 Claude Code 调用。Figma MCP 内部做的事情并不复杂它拿到你提供的 Figma 文件链接和 API Key 后调用 Figma 官方的 REST API 拉取设计稿的 JSON 数据再把这些数据转成 Claude Code 能理解的结构化文本。Claude Code 通过工具调用的方式拿到这些文本然后基于这些内容生成 HTML。所以它和你手动把设计稿截图丢给 AI 看图是有本质区别的截图是像素AI 只能猜MCP 传过来的是设计稿的底层数据尺寸、颜色、字体、间距、层级关系全都清清楚楚生成的代码自然比“看图写代码”严谨得多。3.2 设计稿在 AI 眼里是一棵节点树不是一张图Figma 文件的数据结构本质上是一棵节点树。顶层是页面页面下面有多个 FrameFrame 里嵌套各种元素节点。每个节点都有自己的类型、名称、位置、尺寸、样式属性。Figma MCP 把设计稿数据传给 Claude Code 时Claude Code 看到的其实是这棵节点树的文本化描述而不是视觉画面。我简单列一下它主要能读到哪些东西数据类型能读到的具体信息实际用途布局结构节点类型、名称、层级关系、x/y 坐标、宽高生成 HTML 的 DOM 层级自动布局排列方向、间距、内边距、对齐方式映射生成 CSS Flexbox文字字体族、字号、字重、行高、字间距、对齐、文字内容生成文本样式保留文案填充与描边纯色值、渐变、描边色、边框宽度生成 CSS color、background、border效果阴影、模糊、背景模糊生成 box-shadow、filter素材引用位图图片的引用 key、SVG 矢量路径信息后续导出真实资源举个具体的例子如果设计稿里有个button-primary的 Frame开启了自动布局方向为 HORIZONTAL内部包含一个文字节点内边距是 16px 24px背景色是#2563EB圆角是 8px投影参数是0 4px 12px rgba(0,0,0,0.1)那么 Claude Code 生成的 CSS 基本就会是.button-primary { display: inline-flex; align-items: center; padding: 16px 24px; background: #2563EB; border-radius: 8px; box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); }这就解释了为什么用 MCP 生成的代码比纯看截图生成的代码还原度更高它不是猜的是照着数据翻译的。3.3 能读到的数据和读不到的数据能力边界要心里有数搞清楚 MCP 的能力边界能避免你踩到“AI 漏了某个部分还不知道为什么”的坑。位图图片只能拿到引用 key拿不到真正的图片像素。设计稿里如果有一个产品照片位图MCP 会告诉你这里有一个图片节点但图片内容本身需要调用 Figma 的图片导出接口下载。我在实战里的做法是让 Claude Code 先用占位图生成结构再单独批处理导出资源。组件实例只有组件名和引用信息不一定会展开组件内部完整的图层结构。如果你的设计稿大量使用了嵌套组件AI 可能只识别出“这是一个名为 pricing-card 的组件”至于里面长什么样得再额外解析组件定义。矢量图层的 path 信息非常复杂MCP 返回的是 Figma 内部的节点数据AI 去理解一段复杂的 path 数据并生成 SVG 是可行的但遇到复杂插画时输出可能比较粗糙。设计变量、样式库关联关系这类信息MCP 能带出一部分但不够完整。想让它生成符合你们 Design Token 体系的代码更靠谱的方法是在提示词和项目规范文件里手动约定。说白了Figma MCP 能覆盖的是“布局、结构、基础样式”这三大块覆盖不了的是位图资源、复杂插画和设计系统的高级关联信息。理解了这条边界后面的实操你会顺畅很多。4. 实战流程从一句 Prompt 到完整页面的三次递进操作4.1 设计稿准备交付前清理这些内容生成质量翻倍在让 AI 读设计稿之前设计稿本身的干净程度直接影响生成结果。我在这里总结了四个最关键的整理习惯给 Frame 起有语义的名字。Frame 1920和hero-section对 AI 来说完全不同的信息量名字本身就在告诉 AI 这个区块的作用生成的 HTML 语义标签会更准确。隐藏无关图层。很多设计稿里存了一堆备选方案或历史遗留图层生成前先隐藏掉不要让 AI 去分析那些不参与最终展示的内容。能开 Auto Layout 的尽量开。Figma MCP 能直接读到 layoutModeClaude Code 生成 Flexbox 时基本等于照抄设计稿的自动布局参数没有自动布局的硬坐标稿子生成出来的响应式效果会差很多。把文字和颜色收进 Style。设计稿用了 Text Style 和 Color Style 的地方AI 生成变量命名的可能性更大否则它可能直接在代码里写死颜色值。我做团队内部推广时会直接给设计师一个“AI 交付前自检清单”核心就三句话Frame 命名要能看懂、图层要干净、布局要用自动布局。这比让 AI 事后去理解混乱的稿子高效得多。4.2 Prompt 要这么写把“生成 HTML”升级为“交付可维护页面”很多人第一次尝试时给的指令是“把这个设计稿转成 HTML”结果 Claude Code 确实生成了 HTML但可能就是一张图片式布局完全没法响应式也无法维护。问题不在于 AI 能力而在于你的需求没有讲清楚。我给你一个可直接套用的高质量 Prompt 模板请读取这个设计稿并生成一个响应式页面 https://www.figma.com/design/xxxxxxxx/xxxx?node-id123-456 要求如下 1. 先分析设计稿的布局结构和设计语言用简要文字输出你的理解再开始写代码。 2. 生成单文件 index.htmlCSS 内联在 style 中JS 内联在 script 中。 3. 颜色、圆角、阴影、间距严格按设计稿数据还原颜色值用 CSS 变量定义。 4. 使用系统字体栈保留设计稿中的字体大小、行高、字重。 5. 设计稿中的位图先用灰色占位图代替并在代码中注释标记需要替换的资源名称。 6. 响应式断点为桌面 1440px、平板 768px、移动端 375px。 7. 完成后列出你对还原度的自评特别标注哪些部分可能因为设计稿数据不完整而存在偏差。为什么第 1 条特别重要因为 Claude Code 不是直接“看”设计稿的它先拿到的是设计稿的数据文本。让它先输出结构分析既能让它把信息消化一遍也能让你及时确认它有没有理解错设计稿结构。如果发现分析结果不对马上纠正比生成完代码再返工快得多。4.3 不要一上来就要“完整网站”按页面区块递进生成设计稿如果是一个多区块的落地页我强烈建议不要让 Claude Code 一口气生成整个页面。Claude 的上下文窗口虽然大但设计稿数据量一大MCP 返回的内容会把它“喂饱”后面写代码时容易丢失前面的细节或者输出一段超长的带截断痕迹的代码。更稳的做法是分批生成。以落地页为例流程是先让 Claude Code 读取设计稿输出完整的布局结构清单比如“Header、Hero、Features、Pricing、CTA、Footer”。让它先实现 Header 和 Hero拿到代码后人工确认结构。继续追加 Features 和 Pricing 区域的代码。最后处理 Footer 和整体响应式适配。这个方式和带新人切页面的逻辑是一样的先搭骨架再填内容分步确认才能保证质量。对 Claude Code 来说也一样上下文干净输出质量才稳定。4.4 迭代改稿后续对话就能完成不用重新生成生成初版之后设计师大概率会提几个修改意见。这时候不需要重新贴一次设计稿来一遍直接在 Claude Code 的同一会话里接着提需求就行标题区域的间距再紧凑一点去掉 hero 背景里的阴影按钮 hover 效果改成提亮 10% 而不是加深 10%。Claude Code 会修改对应文件你把文件跑起来确认效果即可。这一步让你的工作方式从“来回手动改 CSS”变成了“提需求、验证、再提需求”效率完全不一样。5. 实际使用中最容易翻车的六个细节5.1 node-id 取错MCP 提示找不到页面这是我最开始踩过的第一个坑。Figma 链接格式通常是这样https://www.figma.com/design/abcdef/项目名?node-id123-456有两种情况需要你注意一是浏览器地址栏里 node-id 有时会是123%3A456这种 URL 编码格式%3A是冒号的编码传给 MCP 时最好还原成123:456二是从设计稿上直接“复制链接”时如果当前选中的不是一个 Frame复制出来的 node-id 可能选中了某个底层小元素导致 AI 读到的结构非常局限。最靠谱的做法是在设计稿里先选中顶层 Frame再到右侧面板的链接区域复制当前 Frame 的链接。这样 node-id 指向的就是一个完整模块AI 拿到的数据才有意义。5.2 自动布局和 Flexbox 并不总是一一对应大多数情况下Figma 的 HORIZONTAL 自动布局对应display: flex; flex-direction: rowVERTICAL 对应flex-direction: column这没问题。但嵌套层级深的设计稿Claude Code 会老老实实把每一层 Frame 都生成一个 div导致 HTML 里出现大量无意义的嵌套标签。理论上这不算错但会让代码变得难维护。我的处理方法是在 prompt 里明确加一句“遇到纯容器型 Frame 且没有样式差异时尽量合并或使用 div 省略结构避免多余的 DOM 嵌套”并让它生成完后自查一遍 DOM 层级是否合理。5.3 位图资源不会自己出现在生成目录里前面提到过设计稿里的图片对 AI 来说只是“一个 image ref”它不会自动把图片下载到你本地。我见过不少人跑完流程后问“为什么生成的 HTML 里图片都是灰色块”其实就是没处理资源这一步。我现在的标准做法是分三条腿走初版生成时用占位图保证结构和样式完整。生成结束后让 Claude Code 输出一个“需要导出的资源清单”列出每个图片节点的名称、所在位置和用途。用 Figma 的图片导出接口批量下载资源或者手动在 Figma 里把位图导出成 WebP再替换到 HTML 里。如果你用的是 Figma 付费版还可以研究一下设计稿里直接右键复制图片的批量方式但不管走哪条路资源导入都是目前替代不了的人工环节。5.4 字体信息最容易出现“看起来对、实际不对”MCP 能把 fontSize、fontWeight、fontFamily 这些数据传给 Claude Code但它不知道你最终部署的网页环境里有没有这些字体。设计师用了一款企业定制字体前端页面压根没引入生成代码里如果直接写font-family: CustomFont实际渲染时就会静默 fallback 到默认字体版式立刻走样。解决方案是在 prompt 或项目规范里提前约定好字体策略。我的做法是字体统一使用系统字体栈设计稿中的英文数字使用 Inter中文使用 PingFang SC / Microsoft YaHei不要引用外部字体文件。这样生成结果至少在所有平台都是“看起来舒服”的等真正需要品牌定制字体时再单独做 Web Font 引入。5.5 API Token 权限不足导致 403反复排查才找到原因这个坑很隐蔽。我用的是老账号早期生成的 Token 权限列表里没有File content: read-only当时觉得“我明明给了 key 啊”结果 Claude Code 调用 MCP 时一直报 403 Forbidden。当时排查了半天最后回 Figma 权限面板一看才发现是自己的 Token 权限没勾全。建议遇到 403 时先做两步用浏览器访问 Figma 文件链接确认文件本身存在且当前账号可访问。检查 Token 的权限范围确保至少包含File content: read-only重新生成一个再试。如果是团队文件还要确认你的 Figma 账号对那个文件有查看权限。很多时候不是工具问题是账号权限问题。5.6 大文件直接击穿上下文生成结果开始“胡言乱语”把整个设计稿链接直接丢给 MCP如果这个文件有几十个页面、几百个 Frame返回的数据量会非常大。这时 Claude Code 的表现是前面还在认真分析后面输出的代码开始出现截断、重复或直接告诉你“我无法一次性处理全部内容”。这不是它偷懒而是上下文确实被塞满了。应对方法有两个只选当前需要生成的 Frame 复制链接不要让 AI 读整个文件的全部内容。如果必须分析整个文件先让 Claude Code 输出页面级的结构概要再逐步深入具体 Frame。我个人的经验阈值是单个 Frame 内部节点在 50 个以内时生成的代码质量比较稳定超过这个数量建议把设计稿拆成更小的功能模块再逐个生成。6. 从“一次生成”到“稳定复用”把 AI 切图嵌进团队工作流6.1 用 CLAUDE.md 固化团队代码规范而不是每次重复打字Claude Code 支持通过根目录的CLAUDE.md文件来读取项目级约定。这个文件会自动进入 Claude Code 的上下文相当于你每次开对话时自带了一份“入职手册”。我的CLAUDE.md长这样# 前端项目生成规范 ## 样式规范 - 颜色一律使用 CSS 变量变量名按用途命名如 --color-primary。 - 圆角统一使用 4px / 8px / 12px 三档。 - 字体栈统一使用系统字体中文优先 PingFang SC、Microsoft YaHei。 - 盒阴影只允许使用设计稿中存在的投影值不允许自创。 ## 结构规范 - 页面区块使用语义化标签header、main、section、footer。 - 纯装饰性节点使用 div功能性节点使用 button、a、input 等标签。 - 避免多余 DOM 嵌套容器层能合并不拆分。 ## 资源规范 - 图片默认使用 assets 目录下的相对路径。 - 初版生成阶段图片用占位图之后统一替换。有了这个文件每次生成代码时 Claude Code 都会自动遵守团队的约定输出结果会更接近你们代码库已有的风格而不是每次生成一套新风格。6.2 建立“组件映射表”让 AI 复用你们的设计系统如果你的项目里已经有现成的组件库比如 Ant Design 或者自研 UI 组件。直接让 Claude Code 从零生成 HTML 反而会导致代码风格和现有库不一致。我的做法是在CLAUDE.md里追加一份组件映射表## 组件映射 - 设计稿中的 button-primary 对应组件库的 PrimaryButton。 - 设计稿中的 input-field 对应组件库的 FormInput。 - 设计稿中的 navbar 对应组件库的 NavBar。这样 Claude Code 生成代码时就会优先调用项目里已有的组件而不是重新写一套相似的按钮和输入框。这不仅让生成速度变快也让 AI 生成的代码真正融入到现有工程里而不是始终停留在“一次性原型页面”的层级。6.3 生成后的质量检查清单这几项必须人工过一遍AI 生成的代码再顺滑也不可能完全替代人工复核。我给自己定了一个检查清单每次生成后按顺序过一遍检查项检查方式常见问题DOM 结构阅读生成的 HTML确认层级合理多余嵌套、缺少语义标签样式还原浏览器打开对比设计稿间距偏差、颜色不一致响应式切换 375 / 768 / 1440 宽度预览布局错乱、图片拉伸资源引用检查所有图片路径是否存在占位图未替换、路径写错交互细节点击按钮和链接确认基本行为hover 效果缺失、链接不跳转可维护性查看 CSS 变量和复用程度大量写死颜色、重复代码块这个清单每次花不了十分钟但能拦住九成以上的低级问题。AI 帮你完成了最耗时间的 70% 工作剩下 30% 的质量把控就是对前端基本功的考验了。6.4 我的最终工作流一句总结加一个小技巧整套流程跑顺之后我现在的日常是设计师在 Figma 里更新完设计稿后我拿到链接简单清理命名复制到 Claude Code生成初版 HTML然后边看边提修改意见。原本需要一整个下午的还原工作现在压缩到一小时内而且大部分时间花在浏览器预览和调整细节上不再需要从头码代码。最后分享一个小技巧别把 Claude Code 当成一键出图的工具它更像一个“能读懂设计稿的实习生”。你给它越清晰的规范它输出的结果越稳定。如果你也想用这套流程建议从一个小页面开始练手别上来就丢一个巨型设计稿过去。跑通一次之后你就会跟我一样再也回不去手动切图的日子了。