Figwright：让 AI 直接驱动 Figma 画布的双向工具

Figwright：让 AI 直接驱动 Figma 画布的双向工具

先一句话说清它是什么：Figwright 通过一个 MCP server 加一个 Figma 插件，利用本地 WebSocket 中转，让 Claude Code、Cursor 这类 AI agent 不仅能“看”Figma，还能直接上手“改”Figma。

官方有一句很精准的描述：Playwright 驱动浏览器，Figwright 驱动 Figma。名字的由来也与此相关，-wright 是英语里“匠人、制造者”的后缀（playwright 写戏、shipwright 造船），Figwright 就是“造设计的匠人”。

它要解决什么问题

如果用过 Figma 官方的 Dev Mode MCP，大概率会碰到两个坎：一是要付费、要有 Dev Mode seat，门槛直接卡住；二是只能读、不能写，agent 看到设计能生成代码，但反过来想把代码或描述变成 Figma 画面，这条路是走不通的。

Figwright 把这两件事都绕开了：

• 免费
  ：走插件通道，免费版 Figma 就能用，不依赖 Dev Mode，不需要任何付费席位。

• 双向
  ：一共 101 个工具，读和写都包含在内。agent 既能照着设计写代码，也能照着代码或描述直接在画布上搭图。

另外一点值得关注：它的代码生成并非“通用型”。很多 Figma 转 Code 的工具吐出来的是一堆通用 div 和硬编码颜色，你还得手动重写一遍。Figwright 会先探测你项目真实的技术栈（框架、样式系统），然后复用你已有的组件、token、图标，只补齐缺失的部分。

它怎么工作

三层架构，全部运行在本地。

最上层是 MCP 客户端，每个 agent 一个（Claude Code、Cursor 等），通过 stdio 走 MCP 协议。

中间是 @figwright/mcp 这个 server，由客户端负责启动。有意思的是它支持多客户端共享：几个 server 会自行选举一个 leader 持有唯一的插件连接，其他 follower 通过 HTTP /rpc 转发调用。当 leader 退出时，follower 自动接管，断线也能续上。这个设计保证了同时开多个 agent 不会互相打架。

最下面是 Figma，桌面版或浏览器版均可。Figwright 插件（基于 Vue 3 编写的 iframe）运行在其中，接收 server 发来的调用，执行真正的 Figma Plugin API。

MCP 客户端 (Claude Code / Cursor)
│
MCP over stdio
▼
@figwright/mcp (leader 选主 + 断线续传)
│
本地 WebSocket + msgpack
▼
Figma 插件 → Canvas 画布

传输走的是本地 127.0.0.1，不联网、不出本机，数据也不会外发。

插件不是黑盒

这一点做得相当用心。插件界面有四个标签：

• Activity
  ：每一次工具调用都被列出来，附带耗时。

• Payload
  ：展示真正发给模型的原始数据，你可以看到 agent 到底拿走了什么信息。

• Context
  ：当前文件、页面、选中内容一目了然。

• Debug
  ：连接健康度显示，还能一键导出诊断包。

换句话说，agent 在背后做了什么、用了什么数据，全程透明可见。这对调试和建立信任都很有帮助。

怎么安装

四步即可完成，参照官方的流程：

在 Claude Code 的 .mcp.json 中添加：

{
  "mcpServers": {
    "figwright": {
      "command": "npx",
      "args": ["-y", "@figwright/mcp@latest"]
    }
  }
}

npx 会自动拉取发布版，无需全局安装。

插件尚未上架 Figma Community 市场，需从 GitHub Release 手动安装。下载最新 Release 的 zip 并解压，在 Figma 桌面版中通过 Menu → Plugins → Development → Import plugin from manifest…，选中解压出来的 manifest.json 即可。

在 Figma 中打开 Figwright 插件（Plugins → Development → Figwright），它会自动连接本地 server，显示 Connected。让 agent 运行一下 ping 确认链路通畅。

skill 能让 agent 在合适的时机主动调用 Figwright：

npx skills add awdr74100/figwright/skills

环境要求：一个 MCP 客户端、Node.js 24 LTS 或更新版本、Figma（免费版即可，但安装插件需要桌面版）。

两个核心工作流

Figwright 的核心理念是 provider-first：不提供一套固定的编译流水线，而是把真实的设计上下文完整地交给模型，让它生成贴合你代码库的代码。这套思路被编码进两个 skill。

Figma → 代码（figma-codegen）

将一个选中的设计转化为“看起来属于这个项目”的代码，而不是通用模板。核心是四个 grounding 工具，模型依靠它们获取真实数据，而非通过截图猜测：

1. get_design_context：获取结构树，将 token 解析为名字（如 Primary/500、spacing/4），对样式进行去重处理，每个实例都附带 mainComponent 和属性。这是布局和绑定的真相来源。
2. component_map：将 Figma 组件映射到你本地代码中的组件，给出 high/medium/low/unmapped 四档状态。high 和 medium 级别的直接复用导入，不需要重新创建。
3. token_map：将 Figma 变量映射到项目 token，映射成功就引用 candidate.ref（比如 bg-primary-500），而不是使用解析出来的原始 hex 值。
4. 导出 grounding 无法直接携带的素材，比如 logo、图片、图标等，否则渲染出来会变成灰块。

这套流程有一条硬性规定：每个 px、每个颜色、每个圆角、每个间距，都必须从 get_design_context 获取，不能靠截图估算。截图只代表视觉意图。另一条准则是“复用优先于重造”：只要 component_map 显示可以复用，就必须直接导入使用，不能自己另起炉灶。

当设计发生变更后，design_diff 会把同一节点存为基线（存放在 .figwright/snapshots/），下次对比时，返回逐节点、逐属性的增删改列表，你只需修改受影响的代码，无需整屏重新生成。

代码 → Figma（figma-build）

反向流程，将代码或描述转化为 Figma 中“看起来本来就属于这个文件”的设计。同样遵循复用优先原则：先用 get_variable_defs、scan_components、get_styles 摸清当前文件已有的设计系统，能够复用的组件就通过 create_instance 实现，颜色走 bind_variable_to_paint，标量走 bind_variable_to_node，共享样式走 apply_style_to_node，避免硬编码 hex 和 px。

使用场景

将上述能力转化为具体能做的事情：

1. 设计还原代码，反复同步。
   设计师修改了一稿，你无需从头切图，agent 运行 design_diff 只更新变化的部分。这是它最日常、最高频的应用场景。

2. 代码反向输出设计稿。
   你已经有 React/Vue 组件了，产品想看看 Figma 里的样子用于评审或展示。figma-build 把组件推送到 Figma，复用文件里已有的组件库，产出的设计不会和现有设计体系脱节。

3. 批量搭建画面。
   101 个工具中包含 batch 工具，可以一次性应用大量编辑。想根据 spec 批量生成落地页、定价区域或整套页面，agent 都能在画布上直接完成。

4. 跨 agent 协作。
   团队成员同时用 Claude Code 连接同一个 Figma 文件，leader/follower 选主机制保证他们不会冲突，谁先启动谁就是 leader。

5. 代码生成时复用真实技术栈。
   团队使用了 Tailwind 加自有组件库，Figwright 会检测出来，生成的代码直接引用你的组件和 token，而不是输出一堆需要你重写的通用标签。

可能踩到的坑

官方 FAQ 写得很实在，挑两个最容易遇到的问题来说。

根因在于 MCP 客户端启动 server 时直接 spawn 命令，不走你的交互 shell，所以 shell 里的 PATH、版本管理器（fnm/nvm/asdf/volta）的配置都获取不到。两种解决办法：一是使用绝对路径，通过 which npx 拿到完整路径填进 command；二是把包装成本地依赖，然后去掉 @latest（@latest 会强制每次启动都去 registry 拉取一次，在被 spawn 的环境里容易卡住或失败）。

server 是由 MCP 客户端启动的，客户端关闭它就会停止。请确认客户端正在运行、插件在同一台机器的同一个 Figma 中（中转走的是本地 127.0.0.1）、本地回环没有防火墙拦截。

与 Figma 官方 Dev Mode MCP 的取舍

如果团队已经全员使用 Figma 付费版，且只需要“看设计写代码”这个单向能力，官方 Dev Mode MCP 更省事，装个插件就能搞定。

Figwright 更适合以下几种情况：不想为 Dev Mode 买单；需要双向能力（既读又写）；希望代码生成能强贴合已有技术栈和组件库；或者想自己 fork 修改工作流（它是开源的，skill 可安装也可修改）。它的代价是需要手动安装插件、配置 MCP、理解 leader/follower 那一套机制，初期上手比官方方案稍重一些。

几句总结

Figwright 的价值不在于“又一个 Figma 转 Code 工具”，而在于两点：一是把 AI agent 和 Figma 的关系从只读变成了双向读写，二是 provider-first 的思路让生成的产物真的能融入你的代码库，而不是进了回收站。如果你正在寻找一种让 AI 深度参与设计到代码、代码到设计循环的方式，并且不想被 Figma 的付费墙拦住，它值得一试。