"Figma 设计稿转 Cursor 代码：Framelink MCP 配置与验收清单"
"figma 设计稿怎么用 cursor 转成代码？用 Framelink MCP 把布局信息喂给 Agent，附 token 配置、选节点工作流，以及从设计稿到 PR 的间距/字体/状态/无障碍检查清单。"
figma 设计稿怎么用 cursor 转成代码，最稳的路径不是截图粘贴，而是让 Agent 直接读 Figma 节点的布局与样式 metadata。Framelink MCP（npm 包名 figma-developer-mcp，仓库 GLips/Figma-Context-MCP）会把 Figma API 返回的结构化数据精简后再塞进上下文，比纯视觉描述更接近「设计稿即 spec」。下面从 MCP 配置、日常工作流、到 PR 前验收，按实施顺序写。
为什么截图喂 Cursor 经常对不准？
截图只有像素，没有层级、约束、组件变体和 design token 名称。Agent 会猜 padding 是 16 还是 20，猜错 hover 态有没有定义。Figma REST API 能返回 frame 树、auto-layout 方向、gap、fontSize、fills 等字段；Framelink 在转发给模型前做了一层「只留 layout 相关信息」的过滤，减少无关字段占用的 token，也降低模型被 hex 色值淹没的概率。
官方 demo 视频（YouTube 6G9yb-LrEqg）展示的是：在 Cursor Agent 模式粘贴 Figma 链接，一次生成接近稿面的 React 组件。一次到位不保证像素级，但结构误差通常比截图流小。
Framelink MCP 是什么、怎么装？
Framelink MCP for Figma 是一个 MCP server，通过 stdio 与 Cursor 通信。Cursor 侧在 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）里声明 server，Cursor 启动 Agent 时会拉起 npx figma-developer-mcp。
前置条件：
- Figma 账号能访问目标文件（至少 view；改稿需 edit）
- Personal Access Token（Settings → Security → Personal access tokens）
- Cursor 已开启 Agent / MCP 支持
macOS / Linux 配置骨架（把 YOUR-KEY 换成 token，勿提交进 git）：
{
"mcpServers": {
"Framelink MCP for Figma": {
"command": "npx",
"args": ["-y", "figma-developer-mcp", "--figma-api-key=YOUR-KEY", "--stdio"]
}
}
}
Windows 把 command 换成 cmd，args 换成 ["/c", "npx", "-y", "figma-developer-mcp", "--figma-api-key=YOUR-KEY", "--stdio"]。
更干净的做法是把 key 放进 env 字段而不是写在 args 里：
{
"mcpServers": {
"Framelink MCP for Figma": {
"command": "npx",
"args": ["-y", "figma-developer-mcp", "--stdio"],
"env": {
"FIGMA_API_KEY": "YOUR-KEY"
}
}
}
}
改完配置重启 Cursor，在 MCP 面板确认 server 绿灯。MCP 能力边界和常见踩坑见Claude Code / Cursor 接 MCP 能做什么。
从选节点到生成组件：推荐工作流
按下面顺序做，返工率最低：
- 在 Figma 里框选目标：选中单个 frame 或 component set，不要整页文件（节点太大会撑爆上下文）。Copy link to selection，URL 里带
node-id。 - 在 Cursor Agent 粘贴链接：prompt 写清技术栈，例如「用 React + Tailwind 实现这个 frame，组件名
PricingCard」。 - 让 Agent 先读布局再写码：明确说「先用 Figma MCP 读取节点结构，列出 spacing 和 typography，确认后再生成代码」。跳过这一步容易漏 hidden layer。
- 对照 design system：若稿里用了 Figma Variables，prompt 里附上项目里 token 的映射表（
--color-primary对应哪个 variable），否则 Agent 会硬编码 hex。 - 本地预览 diff：生成后
pnpm dev并排对照 Figma；差 2px 以内通常可接受，大偏差回到步骤 2 换更小的节点重试。
和Composer 2.5 前端组件写法可以组合：MCP 负责「读稿」，Composer 负责「快速迭代 JSX 和样式微调」。若团队有人用 Claude Code 写逻辑、Cursor 写 UI，分工参考Cursor 与 Claude Code 组合工作流。
MCP 读到的信息够不够用？
Framelink 故意裁剪 API 响应，保留的多是 layout、constraints、部分 style；不保证导出切图、复杂 gradient mesh、或 Figma 插件生成的 exotic effect。典型缺口：
| 设计稿元素 | MCP 通常能读到 | 常见缺口 |
|---|---|---|
| Auto-layout 行列、gap、padding | 是 | 嵌套过深时摘要丢层 |
| 文字 fontFamily / size / weight | 是 | 自定义字体需本地已安装 |
| 颜色 fills | 是（hex/rgba） | gradient Stop 可能简化 |
| Component variant（hover/disabled） | 部分 | 未命名 variant 易被忽略 |
| 图片 fill | 节点 ID | 二进制需另下或占位 |
| Prototype 交互 | 否 | 要手写状态机 |
所以「figma 设计稿怎么用 cursor 转成代码」的 realistic 预期是：结构 + 主样式一次生成，状态态和响应式 breakpoint 要你补 prompt 或手写。
从设计稿到 PR 的验收检查清单
生成代码只是 halfway。提 PR 前按这张表过一遍，避免设计验收打回：
间距与尺寸
- 主容器 padding/margin 与 Figma inspect 一致（允许 ±1px 若项目用 rem 换算）
- Auto-layout gap 未写死 magic number，优先用 token 或 theme spacing scale
- 图标与文字 baseline 对齐，非「看起来差不多」
字体
- font-family 落在项目已加载字体栈内
- 字重、行高、letter-spacing 与稿一致；长文案处检查 truncate / line-clamp
状态
- default / hover / focus / disabled / loading 五种至少覆盖稿里出现过的
- focus ring 可见，不只
:hover伪类
无障碍
- 交互元素是
<button>或带 role + keyboard handler，不是裸<div onClick> - 图标按钮有
aria-label - 正文与背景对比度 WCAG AA（4.5:1 正文，3:1 大字）；用浏览器 DevTools 或 contrast checker 抽测
- 表单控件有
<label>或aria-labelledby
工程
- 无硬编码 Figma 节点 ID 进生产代码
- 图片走 CDN 或 assets 目录，非 hotlink Figma API
- Storybook / 单测（若有）覆盖主 variant
这张清单可以直接贴进 PR template 的「Design QA」小节。
权限、安全与团队稿
Personal Access Token 权限跟随你的 Figma 账号：能看见的文件才能读，离职账号 token 应轮换。不要把 token 写进仓库；用环境变量或 Cursor 本地 mcp.json（已在 .gitignore 的 path）。
客户保密稿、未公开 redesign，走公司 Figma 的 view-only 链接仍会把结构发给 MCP 进程和下游模型。敏感项目应使用脱敏副本 file，或内网自建 MCP 网关审计日志。
团队 design system 若用 Figma Organization library，确认 token 对 Agent 账号可见；否则 MCP 只能看到 detached hex，变量名对不上代码里的 theme.colors.brand。
截图流 vs MCP 流：什么时候换方案？
两种输入方式不是非此即彼，按任务类型选：
| 场景 | 推荐输入 | 原因 |
|---|---|---|
| 新组件从 0 到 1 | Figma MCP 链接 | 有 gap、padding、层级树 |
| 微调已有页面某个按钮颜色 | 截图 + 「只改 primary 按钮 background」 | 改动小，读 API 反而慢 |
| 设计稿用了 heavy blur / mesh gradient | 截图 + 人工描述 fallback | API 常简化效果层 |
| 批量落地 6 个同类卡片 | MCP 读 component set | variant 名能进 prompt |
| 设计师只给了 PDF 导出 | 截图 | 没有 Figma 源文件 |
MCP 流的隐性成本是 token：一次读中等 frame 可能吃掉几千 token 的工具返回。若项目已有 .cursorrules 限制上下文，先读上下文窗口管理里「工具目录膨胀」一节，避免同一轮里再挂五六个无关 MCP。
第一次跑通时的典型报错
401 / Invalid token：token 复制多了空格，或 token 已被 Figma 撤销。重新生成 PAT，更新 mcp.json 后完全退出 Cursor 再开。
403 / File not found：链接里的 file key 对，但你的账号没有该 team project 权限。让设计师 share 到「can view」，或换 personal draft 副本测通。
节点为空 / No children：URL 没带 node-id，Agent 读的是整文件根节点但摘要被截断。务必 Copy link to selection。
生成代码全是 inline style：prompt 没约束栈。补一句「项目用 Tailwind v4 + shadcn，禁止 inline style，颜色用 CSS variable」。
和图片差一截：常见是 border-radius 或 box-shadow 在 API 摘要里被省略。打开 Figma inspect 补两项，或截图局部让 Agent 只修 shadow。
和 design handoff 文档怎么配合？
单靠 MCP 不能替代设计说明。建议在 Figma 同页加一页「Handoff」frame，纯文字列出：breakpoint 行为、空态文案、错误态、埋点 id。Agent 读 layout frame 之前先 @ 这个 Handoff frame 的链接，生成代码时会把业务规则一起带上。
若团队用 Storybook，生成组件后补一条 story：Default、Hover、Disabled、Loading 四态。设计验收不再靠「肉眼对 Figma 网页」，而是 reviewer 在 Storybook 里点。这和前面 PR 检查清单里的状态节是同一套标准，只是提前到组件级。
常见问题
Cursor 里 MCP 显示连接失败怎么办？
先终端手动跑 npx -y figma-developer-mcp --figma-api-key=$FIGMA_API_KEY --stdio，看是否报 token 无效。Windows 检查是否用了 cmd /c 包装。Node 版本过旧也会导致 npx 拉包失败。
可以一次转换整页 Landing 吗？
不建议。整页节点树太大，模型会省略 section。按 section frame 拆分，每帧一个 PR commit，最后拼页面。
和 Figma Dev Mode 手写 CSS 比哪个快？
Dev Mode 适合人眼抄码；MCP 适合整组件骨架。Dev Mode 给的 CSS 往往不适配你的 Tailwind 约定，Agent 生成时声明「用 Tailwind utility，不要 inline style」更一致。
设计改了还要重跑 Agent 吗？
小改（颜色 token）人工 diff 更快。结构改（列数、breakpoint）重新 paste 新 node 链接让 Agent 读新版更稳。