内容
<p align="center">
<img src="assets/banner.png" alt="Design Bridge — 从输入的规范中编写真实的 Figma 设计" width="820">
</p>
<p align="center">
<a href="https://www.npmjs.com/package/figma-design-bridge"><img src="https://img.shields.io/npm/v/figma-design-bridge?color=1F9E75&label=npm" alt="npm 版本"></a>
<a href="https://github.com/evidence-codes/figma-design-bridge/actions/workflows/ci.yml"><img src="https://github.com/evidence-codes/figma-design-bridge/actions/workflows/ci.yml/badge.svg" alt="持续集成"></a>
<a href="LICENSE"><img src="https://img.shields.io/npm/l/figma-design-bridge?color=1F9E75" alt="MIT 许可证"></a>
<img src="https://img.shields.io/node/v/figma-design-bridge?color=1F9E75" alt="Node 版本">
</p>
# 设计桥
一个 MCP 服务器，允许 AI 代理（Claude Code 或任何 MCP 客户端）根据小型输入规范在 Figma 画布上编写真实的设计 — 自动布局框架、实时文本、颜色变量。
Figma 的 REST API 无法创建设计节点；只有在 Figma 内部运行的插件 API 代码才能。 因此，设计桥由三个部分组成：MCP 服务器，代理与之通信、本地 WebSocket 和 Figma 插件，负责实际构建。
```
代理 → MCP 服务器 → ws://127.0.0.1:3055 → 插件 UI iframe → 插件沙盒 → 画布
```
<p align="center">
<img src="assets/demo.gif" alt="输入的规范变为 Figma 画布上的渲染框架" width="820">
</p>
<sub>流程图示 — `render_screen` 规范变为画布上的真实自动布局。</sub>
## 设置
您需要运行两个部分：服务器（一次）和插件（每个 Figma 文件）。大约需要两分钟。 需要 **Node 18+** 和 **Figma 桌面应用程序**（插件不能在浏览器中运行）。
**0. 预检（可选）**
```bash
npx -y figma-design-bridge --doctor
```
检查您的 Node 版本和端口是否空闲，然后打印确切的下一步骤。 如果任何连接失败，请先运行它。
**1. 将服务器注册到您的 MCP 客户端**
无需克隆 — 直接从 npm 运行：
```bash
claude mcp add figma-bridge -- npx -y figma-design-bridge
claude mcp list # 应该显示 figma-bridge
```
<details>
<summary>其他 MCP 客户端（Cursor、Windsurf、Claude Desktop）</summary>
任何 MCP 客户端都有效 — 指向相同的命令。 将以下内容添加到客户端的 MCP 配置（`.mcp.json`、`.cursor/mcp.json` 或 Claude Desktop 的 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"figma-bridge": {
"command": "npx",
"args": ["-y", "figma-design-bridge"]
}
}
}
```
</details>
<details>
<summary>或从克隆运行</summary>
```bash
git clone https://github.com/evidence-codes/figma-design-bridge
cd figma-design-bridge
npm install
claude mcp add figma-bridge -- node "$(pwd)/src/server.js"
```
</details>
**2. 在 Figma 中加载插件**
- **从 Figma 社区：** （链接一旦发布）- 点击安装，然后从 `插件 → 设计桥` 运行。
- **从源代码：** 获取 [`design-bridge-plugin.zip`](https://github.com/evidence-codes/figma-design-bridge/releases/latest) （或使用克隆的 `plugin/` 文件夹）。 Figma 桌面应用程序 → 打开设计文件 → 右键单击画布 → `插件 → 开发 → 导入插件从清单…` → 选择 `plugin/manifest.json`，然后运行 `插件 → 开发 → 设计桥`。
一个带有绿色点的面板在找到服务器时出现。 **保持该面板打开** — 关闭它会杀死套接字。
**3. 检查线路**
要求您的代理调用 `figma_status`。 您应该返回文件和页面名称。
## 工具
| 工具 | 功能 |
|---|---|
| `figma_status` | 连接检查。 当出现问题时从这里开始。 |
| `render_screen` | 根据规范构建屏幕。 相同的 `key` 替换到位。 |
| `create_variables` | 创建颜色变量集合。 |
| `list_screens` | 此桥渲染的所有内容，带有密钥。 |
| `delete_screen` | 按密钥删除一个。 |
## 烟雾测试
在一切连接完成后，将以下内容粘贴到您的代理中：
> 使用 `render_screen` 并带有此规范：
> ```json
> {
> "key": "smoke-test",
> "name": "烟雾测试",
> "width": 600,
> "background": "#FBFBF9",
> "root": {
> "type": "frame", "layout": "col", "gap": 16, "pad": 32, "width": "fill",
> "children": [
> { "type": "text", "content": "提取范围",
> "font": "Inter", "weight": "Semi Bold", "size": 24, "color": "#14201C" },
> { "type": "frame", "layout": "row", "gap": 12, "pad": [12, 16],
> "fill": "#E7F0EB", "radius": 8, "width": "fill",
> "children": [
> { "type": "text", "content": "声明", "font": "Inter",
> "weight": "Medium", "size": 12, "color": "#1F5F45" },
> { "type": "text", "content": "五页营销网站",
> "font": "Inter", "size": 14, "color": "#14201C" }
> ] }
> ]
> }
> }
> ```
一个带有真实自动布局的框架应该出现在您的画布上。 运行两次 — 第二次运行替换第一次运行，而不是堆叠重复项。
## IR
`src/schema.js` 是合同。 三种节点类型：
- **frame** — 唯一容器。 `layout`（`row`/`col`/`none`）、`gap`、`pad`、`align`、`justify`、`fill`、`stroke`、`radius`、`width`（`hug`/`fill`/`fixed`）。
- **text** — `content`、`font`、`weight`、`size`、`lineHeight`、`color`。
- **rect** — `w`、`h`、`fill`、`stroke`、`radius`。
所有内容都一一映射到 Figma 概念上。 这是故意的：没有 CSS 需要反向工程，没有布局引擎，没有猜测 `div` 本来是什么。 保持小规模 — 您添加的每个字段都是插件必须处理和模型必须学习的字段。
## 配置
服务器监听 `127.0.0.1:3055`。 要更改它，请传递 `--port <n>` （或设置 `FIGMA_BRIDGE_PORT` ）**和**在插件面板的 **端口** 字段中输入相同的端口 — 两个部分必须同意。 `npx figma-design-bridge --doctor` 将告诉您默认端口是否已占用。
运行 `npx figma-design-bridge --help` 获取所有标志。
## 可能出现的问题
**Figma 中必须存在字体。** 插件在构建前加载规范中的每个字体。 如果 Figma 没有它，渲染会以清晰的消息失败，而不是静默替换。 `weight` 是 Figma 的样式名称 — `"Regular"`、`"Medium"`、`"Semi Bold"` — 而不是 CSS 数字。
**`width: "fill"` 需要一个自动布局父级。** 在 `layout: "none"` 框架内，它被忽略。 这会软失败而不是抛出，因此屏幕看起来微妙地错误通常是这种情况。
**一次一个套接字。** 连接的第二个 Figma 窗口会断开第一个。 如果渲染开始进入错误的文件，那就是原因。
**密钥是您迭代的方式。** 重新渲染 `"review-screen"` 会替换它。 更改密钥，您将获得第二个副本 — 对于比较变体很有用，意外时很麻烦。
## 缺少的内容
组件和变体（`figma.createComponent`、`combineAsVariants`），将变量绑定到节点属性而不是仅创建它们，图像和多页面定位。 这些是此停止成为玩具的地方 — 欢迎贡献。
[`cursor-talk-to-figma-mcp`](https://github.com/sonnylazuardi/cursor-talk-to-figma-mcp) 是一个开源实现，具有相同的架构，但功能更全面。 设计桥为了小而严格的 IR 进行交易：一个规范渲染整个屏幕，每个字段映射到一个 Figma 概念，并且没有布局引擎来对抗。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
