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 工具，模型依靠它们获取真实数据，而非通过截图猜测：
get_design_context：获取结构树，将 token 解析为名字（如Primary/500、spacing/4），对样式进行去重处理，每个实例都附带mainComponent和属性。这是布局和绑定的真相来源。component_map：将 Figma 组件映射到你本地代码中的组件，给出 high/medium/low/unmapped 四档状态。high 和 medium 级别的直接复用导入，不需要重新创建。token_map：将 Figma 变量映射到项目 token，映射成功就引用candidate.ref（比如bg-primary-500），而不是使用解析出来的原始 hex 值。- 导出 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。
使用场景
将上述能力转化为具体能做的事情：
- 设计还原代码，反复同步。 设计师修改了一稿，你无需从头切图，agent 运行
design_diff只更新变化的部分。这是它最日常、最高频的应用场景。 - 代码反向输出设计稿。 你已经有 React/Vue 组件了，产品想看看 Figma 里的样子用于评审或展示。
figma-build把组件推送到 Figma，复用文件里已有的组件库，产出的设计不会和现有设计体系脱节。 - 批量搭建画面。 101 个工具中包含 batch 工具，可以一次性应用大量编辑。想根据 spec 批量生成落地页、定价区域或整套页面，agent 都能在画布上直接完成。
- 跨 agent 协作。 团队成员同时用 Claude Code 连接同一个 Figma 文件，leader/follower 选主机制保证他们不会冲突，谁先启动谁就是 leader。
- 代码生成时复用真实技术栈。 团队使用了 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 的付费墙拦住，它值得一试。
