把 Figma 链接丢给 AI，再补一句“请完美还原”，通常能得到一个看起来差不多的页面。真正开始对照设计稿，问题才会出现：按钮矮了几像素，标题换行不一样，图标被换成另一套，桌面能看，手机上却挤成一团。

问题往往出在上下文不完整。截图告诉模型页面长什么样，却没有完整解释组件、变量、布局约束和交互状态；Figma 返回的设计信息，也不会自动告诉它项目里已经有哪个按钮、哪个表单和哪套路由。

我更愿意把这件事拆成一条可以检查的流程：用 Figma MCP 读取设计，用仓库组件承接设计，再用真实浏览器验收。 Claude Code 和 Codex 都可以参与，切换工具时，把设计依据、已经完成的修改和待修问题留在项目里。

下面使用 Claude Code 与 Codex CLI 接入 Figma。重点是设计到代码的实现流程，以及两套工具之间怎样少丢上下文。

先把三者的职责分清楚

Figma 提供目标画框、样式、变量和素材；编码工具负责理解这些信息、读取仓库并修改代码；浏览器负责暴露代码运行后的真实效果。三者需要连起来看。

Mermaid
flowchart TD
  F["Figma：指定画框与状态"] --> M["Figma MCP：结构、截图、变量"]
  M --> C["Claude Code 或 Codex"]
  R["仓库：组件、样式与业务逻辑"] --> C
  C --> I["实现到现有项目"]
  I --> B["浏览器：视觉与交互验收"]
  B --> D["差异记录：位置、尺寸、状态"]
  D --> C
  C --> H["项目内的交接文件"]
  H --> N["另一个编码工具接着处理"]

正在加载图表…

这里说的“无缝”，指的是两边能读取同一份设计依据和项目状态。它们的登录、MCP 配置和聊天记录仍然各自独立，不会因为连接了同一个 Figma 文件，就自动共享上一轮对话。

也不必强行给模型安排固定身份。可以让 Claude Code 做第一版、Codex 做复核，也可以反过来。更重要的是同一时刻谁负责改文件、另一方依据什么复核，避免两个进程一起覆盖同一段代码。

第一步：把 Figma MCP 接到两个客户端

Figma 有远程服务和桌面服务两种入口。先选一种跑通，通常已经够用。

左右滑动查看完整表格

接入方式

地址

适合的场景

远程 MCP

https://mcp.figma.com/mcp

用画框链接读取设计，不依赖本机开启 Figma 桌面服务

桌面 MCP

http://127.0.0.1:3845/mcp

Figma 桌面应用和编码工具在同一台机器，使用当前选区

Figma 在 2025 年已推出远程 MCP，可以通过链接获取设计上下文。Figma 远程 MCP 发布说明

以下假设两个 CLI 已经安装，且你有目标 Figma 文件的访问权限。Claude Code 的终端入门可以先看 安装与第一次使用。MCP 是否可用还与 Figma 账号、席位和组织设置有关；文件能在浏览器打开，不等于所有工具调用都有权限。

Claude Code：添加服务，再完成授权

在终端执行：

bash
claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp

这里使用用户范围，让这个 MCP 配置能用于该机器上的多个项目。已有名为 figma 的配置时，先检查它的地址，不要重复添加。

bash
claude mcp get figma

重新启动 Claude Code，在会话里输入 /mcp，选择 Figma 并按提示完成本人授权。确认连接状态后，再给它一个自己有权访问的小画框链接，要求读取标题和布局。配置存在、授权成功和能够读到目标设计，是三个不同的检查点。Figma 的 Claude Code 接入步骤

Codex：单独添加同一个服务

在终端执行：

bash
codex mcp add figma --url https://mcp.figma.com/mcp

如果添加时没有完成 OAuth 授权，再执行登录命令，并检查服务列表：

bash
codex mcp login figma
codex mcp list

Codex 的 MCP 配置与 Claude Code 分开管理。不要把 Claude 的 JSON 配置直接粘进 Codex 的 TOML 文件；使用各自 CLI 添加服务更容易避免格式错误。配置后启动新的 Codex 会话，也用同一个小画框验证读取结果。Codex MCP 文档、Figma 的 Codex 手动接入步骤

授权由本人在官方页面完成。项目仓库可以保存接入说明，不需要保存个人 token。

使用桌面服务时，留意 localhost 属于哪台机器

如果想直接读取 Figma 当前选区，先在 Figma 桌面应用中启用 Dev Mode 的 MCP 服务，再把客户端指向本地地址。例如，Claude Code 可以这样配置：

bash
claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp

Codex 对应的是：

bash
codex mcp add figma-desktop --url http://127.0.0.1:3845/mcp

桌面服务需要 Figma 应用保持运行。若 Figma 在 Mac 上，而 CLI 跑在 SSH 连接的服务器里，服务器的 127.0.0.1 指向服务器自身，当然读不到 Mac 上的服务。这个场景优先考虑远程 MCP；没有必要为了接入，把本地 MCP 端口直接开放到公网。Figma 桌面服务说明

远程和桌面服务同时配置时，在提示中明确本次使用哪一个，避免模型拿了桌面旧选区，却以为自己读的是你刚贴的链接。

第二步：给具体画框，同时说明要实现哪种状态

从 Figma 选中目标 Frame，复制该选区的链接。相较于只给文件首页，带 node-id 的链接更容易定位到具体页面或组件。通常一个页面里还有默认、加载、空数据、错误和弹窗等状态，不能只说“实现这个文件”。

第一次提示，我会把目标写成下面这样。方括号里的内容需要替换为真实项目的信息：

代码
请读取这个 Figma 画框：[粘贴具体画框链接]。

本次只实现账号设置页的默认状态和保存中状态。
项目技术栈：[填写实际框架和样式方案]。
页面入口：[填写路由或文件路径]。
组件目录：[填写仓库实际组件目录]。

先获取设计上下文和画框截图，列出页面结构、关键尺寸、
文字样式、颜色变量、素材以及可复用组件。
暂时不要修改代码；对设计缺少的状态和响应式规则单独说明。

设计信息可以分几次读：get_design_context 获取目标节点的上下文，get_screenshot 提供视觉参照，get_variable_defs 辅助确认变量与样式。get_metadata 适合先看层级，再选中需要深入的子节点。Figma MCP 工具说明

如果返回被截断、只给出很少的结构，先不要让模型凭空补全。把页面拆成页头、侧栏、表单卡片或弹窗，分别读取完整信息，再组合实现。Figma 也建议避免一次选择过大的画框。大画框处理建议

截图用来判断结果是否一致，结构和变量用来解释怎样实现。整张设计截图不能直接充当页面背景，否则外观看似接近，文字、表单、按钮和响应式行为都无法正常工作。

第三步：让设计落到仓库已有的组件上

设计读完以后，先扫描项目里的基础组件、图标、字体和样式变量。尤其已有设计系统的项目，重画一个 Button 往往比复用它更容易出错：视觉可能相近，键盘焦点、禁用态和加载态却不一致。

如果团队已经配置 Code Connect，MCP 可以把 Figma 组件与代码组件的对应关系带入上下文。要检查映射到的具体组件和属性，并在那个设计节点上复用；映射不是一句“尽量使用组件库”的泛泛提醒。Code Connect 与 MCP

没有 Code Connect 也可以先做一张小表。下面是一个示例映射，目录和数值都需要根据自己的设计与仓库填写：

左右滑动查看完整表格

Figma 中的元素

项目里优先寻找

实现前要核对

Primary Button

Button 的主要操作变体

高度、左右内边距、禁用与加载状态

Text Field

Input 与表单错误组件

字号、标签关系、错误提示占位

Settings Card

已有 Card 或容器样式

边框、圆角、内边距、宽度约束

正文与弱化文字

字体和颜色 token

字体是否加载、字重和行高是否一致

图标与插图

同一素材或相同图标组件

图形、描边、比例和实际显示尺寸

需要新增的值，先判断能否映射到已有 token；确实是页面特有的尺寸，再放到页面作用域。不要为了还原一个卡片，直接改变全站所有按钮或标题的样式。

接下来给实现任务时，把这一层关系说清楚：

代码
根据已经读取的画框开始实现。

先检查现有组件和样式 token，复用已确认的组件映射。
使用项目原有路由、表单和数据获取方式。
布局用符合页面约束的 Flex/Grid，不照搬整页绝对定位。
静态图标和插图使用设计对应素材，保留比例，不用相似图标替代。
只修改目标页面及必要的局部样式，不重写无关页面。

完成后说明修改文件、复用组件、缺少的设计状态和验证方式。

对于需要保存到项目的素材，要记录来源并按项目流程落到可维护的位置。Figma 返回的临时资源地址可以帮助开发取图，不适合原样作为线上长期依赖。检查时既看文件是否存在，也看它是否出现在正确位置、有没有拉伸或裁切错误。

一个例子：把画框约束翻译成响应式布局

假设设计里是左侧标题说明、右侧表单的设置页。桌面是两列，窄屏需要上下排列。下面只是布局示例，320px、24px 和 760px 是为说明规则选择的数值，不是从某个真实 Figma 文件测得的结果。

css
.settings-layout {
  display: grid;
  grid-template-columns: minmax(0, 320px) minmax(0, 1fr);
  gap: 24px;
  align-items: start;
}

.settings-layout > * {
  min-width: 0;
}

@media (max-width: 760px) {
  .settings-layout {
    grid-template-columns: minmax(0, 1fr);
  }
}

这里真正需要交给模型的是规则：说明栏有最大布局宽度，表单占剩余空间，子元素允许收缩，窄屏变成一列。用几个 left、top 把两个区域摆到截图位置，只解决了某一个宽度下的静态画面。

Figma 没有手机稿时，也不要把自己猜的断点写成“设计就是如此”。把它记成实现假设，再用真实内容检查：标题变长会怎样，错误消息会不会把按钮推出屏幕，浏览器放大以后是否还能使用。

业务状态也需要另外接上。设计里的“保存中”可以对应按钮禁用和进度提示，但“保存成功”必须由真实请求结果驱动。先用假数据搭视觉时，应明确标记接口尚未接入，不能让漂亮的成功提示掩盖失败请求。

第四步：用同一份项目规则连接 Claude Code 和 Codex

如果两套工具轮流参与，同一套约束就不应该维护两份。可以把公共规则放在仓库根目录的 AGENTS.md，再让 CLAUDE.md 引用它。

Codex 会读取适用的 AGENTS.md，Claude Code 的 CLAUDE.md 支持通过 @ 引入文件。Codex 项目指令、Claude Code 文件导入

把下面这段作为项目规则的一部分，而不是覆盖仓库原来的完整规则：

markdown
## Figma 到代码

- 实现前读取具体画框的设计上下文与截图。
- 先检查仓库组件、图标、字体和 token，保留有效的组件映射。
- 设计没有说明的状态或响应式规则，记录为待确认项或实现假设。
- 只修改当前任务范围，不替换无关布局和全局样式。
- 使用与设计一致的文案和测试数据进行截图比较。
- 交付时分别说明视觉、交互和接口验证结果。

如果两个文件位于同一目录，可以在现有 CLAUDE.md 中追加：

代码
@AGENTS.md

规则放好后，分别让两个工具说明它们读取到了哪些约束。子目录还可能有更具体的规则；不要仅凭文件存在，就假定当前任务已经加载了它。

这些文件同步的是工作要求。正在处理哪个 Frame、已经改到哪里、哪些差异还没有修复，需要另外留下交接记录。

第五步：交接设计依据和当前差异，不只交接一句“继续”

我会为页面放一份短文件，比如 docs/ui/settings-handoff.md。下面是交接模板，不代表某个页面已经完成了这些检查：

markdown
# Settings UI 交接

## 设计依据
- Figma 画框链接：[填写]
- 状态：默认、保存中、错误提示
- 参照截图及视口：[填写路径与尺寸]

## 当前代码
- 分支或提交：[填写]
- 工作区未提交改动：[填写文件及用途]
- 页面入口、预览地址和启动命令：[填写]
- 复用的组件和 token：[填写]

## 已验证
- 只记录实际运行过的命令、交互和截图检查。

## 待处理
- 差异位置、设计值、当前值、判断依据：[填写]
- 尚未接入的接口或缺少的设计状态：[填写]

切换工具前，让正在写代码的一方停止编辑。接手的一方先看规则、交接文件和当前 Git diff，再决定下一步，不能只按旧聊天摘要重新生成一遍页面。

比如第一版由 Claude Code 完成，交给 Codex 复核时可以这样说：

代码
先阅读 AGENTS.md、docs/ui/settings-handoff.md 和当前 Git diff。
用交接文件中的同一个 Figma 画框复核现有实现。

先不要改代码。列出仍然存在的视觉与交互差异：
每项包含位置、设计依据、浏览器中的实际表现和建议修改范围。
不要把已经通过的部分重写，也不要凭主观喜好重新设计。

复核之后，再把确认的问题交给其中一个工具修改。这样做不依赖某个模型永远擅长设计或永远擅长代码，而是让下一步有可以检查的起点。

第六步：把“差不多”变成能定位的差异

视觉对照前，先统一视口、文案、数据和状态，并等字体与图片加载完成。否则同一段文字在不同字体下换行，可能让下面整张卡片都错位，看起来像间距问题，根源却是字体缺失。

可以先检查页面大结构，再看卡片、控件和图标。每一轮修复后回到相同条件重新观察，避免一次改动太多，失去对差异来源的判断。

下面是一张示例差异表，数值用于展示怎样记录，不能当作本项目的实测成绩：

左右滑动查看完整表格

项目

示例设计值

示例实现值

应追查的位置

按钮高度

40px

36px

是否选择了错误的组件尺寸变体

卡片内边距

24px

16px

页面容器 token 或局部覆盖

图标宽高

20 × 20px

24 × 24px

素材根尺寸与容器缩放

标题行高

32px

28px

字体样式及字体是否成功加载

在自己的开发页面中，可以给目标元素加一个稳定的选择标识，然后通过浏览器控制台检查尺寸。下面这段只读取页面：

javascript
const element = document.querySelector('[data-ui="save-button"]');
if (!element) {
  console.warn('没有找到保存按钮，请先核对选择器');
} else {
  const rect = element.getBoundingClientRect();
  const style = getComputedStyle(element);
  console.table({
    width: rect.width,
    height: rect.height,
    fontSize: style.fontSize,
    lineHeight: style.lineHeight,
    paddingInline: style.paddingInline,
  });
}

尺寸一致还不够。要继续看字重、基线、图标描边、图片裁切和明暗层级。截图叠加或视觉回归测试能辅助定位，但不同系统的字体渲染可能产生像素差异，不应把一个机械的相似度百分比当作“完美还原”的唯一标准。

同时手动走一遍关键操作：Tab 能否依次访问控件，焦点是否可见，禁用按钮是否真的不能提交，错误提示是否能被理解，窄屏和长文案会不会溢出。Figma MCP 提供设计上下文；浏览器操作与截图验证仍需要相应工具或人工完成。

接入与还原时，最常见的几个卡点

问题

优先排查

添加了 MCP，却没有工具

当前客户端是否重启、服务是否连接、是否加在另一台机器或另一作用范围

登录成功，读取画框仍被拒绝

OAuth 对应账号、文件权限、组织设置与可用额度

读到错误的页面

链接是否含具体 node-id、桌面选区是否变化、是否选错 MCP 服务

返回内容过长或不完整

缩小到具体区域，先读层级，再读取需要的子节点

生成了项目没有使用的技术栈

在提示中明确实际框架、样式方案、组件目录和路由约定

换一个工具，组件又被重写

是否传入公共规则、组件映射、交接记录和已有 diff

本地图片正常，上线后丢失

是否仍引用本机服务或临时素材地址，构建产物是否包含素材

桌面接近设计，手机却溢出

是否缺少响应式规则、长内容检查和窄屏验收

遇到这些问题，先修复缺失的信息或连接环节，再重试对应区域。整个页面反复推倒重来，往往会把已经正确的部分也带偏。

对我来说，这套工作流最有用的地方，是每一步都有明确产物：具体画框、设计截图、组件映射、可运行的页面，以及有依据的差异记录。Claude Code 和 Codex 可以轮流完成这些工作，而 Figma 与浏览器始终是它们共同对照的依据。