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 在背后做了什么、用了什么数据，你全程可见。这对调试和信任都很有帮助。

怎么装

四步，我按官方的顺序贴。

1. 配置 MCP server。 在 Claude Code 的 .mcp.json 里加：

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

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

2. 装 Figma 插件。 插件还没上 Figma Community 市场，从 GitHub Release 手动装。下载 最新 Release 的 zip 解压，Figma 桌面版里走 Menu → Plugins → Development → Import plugin from manifest...，选解压出来的 manifest.json。

3. 连接。 在 Figma 里打开 Figwright 插件（Plugins → Development → Figwright），它自动连本地 server，显示 Connected。让 agent 跑一下 ping 确认链路通。

4.（可选）装 skill。 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/），下次再 diff，返回逐节点、逐属性的增删改，你只改受影响的代码就行，不用整屏重生成。

代码 → 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 选主机制让他们不打架，谁先开谁领导。

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

可能踩的坑

官方 FAQ 写得很实在，挑两个最容易碰的。

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

插件一直 Waiting 连不上。 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 付费墙挡住，值得一试。

仓库地址：github.com/awdr74100/f...，MIT 协议。