Cursor 的 Composer 可以编写大量 UI 代码。但它无法读取你的 Figma 文件。粘贴截图只会让它猜测——间距错误、颜色值凭空生成、组件名称在代码库中根本不存在。问题不在于模型，而在于缺少结构化上下文。

figmascope 解决了这个问题。它将你的 Figma 文件导出为 zip 包：设计 Token、逐屏布局树、2× 参考渲染图、组件清单和 UI 字符串——Cursor 的 Agent 生成精准代码所需的一切，而不仅仅是看起来合理的代码。

本指南涵盖完整流程：Figma URL → 上下文包 → Cursor 提示词 → 审查输出。

包的内容

figmascope 导出你的文件时，zip 包包含：

包保存在你的设备上，不会重新上传到任何地方。

第一步：生成包

前往 figmascope，将你的 Figma 文件 URL 粘贴到输入框。导出程序在浏览器中针对 Figma REST API 运行——第一次需要个人访问令牌（存储在 localStorage 中，不会发送到 figmascope 服务器）。

点击导出 Agent 上下文。页面处理每个框架、解析 Token、构建 IR，然后将 context-bundle.zip 下载到你的设备。

如果你的文件有很多框架，只有不是组件或缩略图的顶层框架会被包含。_meta.json 准确显示导出了哪些框架以及任何警告（渐变填充、不受支持的效果）。

第二步：解压到项目目录

将包放在 Cursor 可以看到的位置——仓库根目录下的 design/ 目录是最清晰的结构。

# 在项目根目录
unzip ~/Downloads/context-bundle.zip -d ./design/

# 验证结构
ls design/
# CONTEXT.md  _meta.json  components/  screens/  strings.json  tokens.json

如果不想提交包，将 design/ 添加到 .gitignore。或者提交它——它是确定性的；同一 Figma 文件在相同状态下总是生成相同的包，所以差异是有意义的。

第三步：添加 .cursorrules 片段

Cursor 读取仓库根目录的 .cursorrules，并将其添加到每个聊天上下文的开头。这是将 Agent 连接到包的地方。

# .cursorrules

构建 UI 屏幕时：
1. 首先读取 ./design/CONTEXT.md。它规定了目标框架和约束。
2. 使用 ./design/tokens.json 中的 Token 作为所有间距、颜色、圆角和字体排版值。
3. 参考 ./design/screens/<name>.json 获取布局结构和节点层级。
4. 使用 ./design/screens/<name>.png 进行视觉确认——用作合理性检验，而非真相来源。
5. 使用 ./design/strings.json 中的字符串键，而非硬编码 UI 文案。
6. 不要发明 Token 值。如果 tokens.json 中没有某个值，请标记它。

这个单一代码块防止了三种最常见的偏移来源：发明的颜色、硬编码的字符串和从截图猜测布局。

第四步：打开 Cursor Composer 并实现屏幕

打开 Composer（macOS 上 Cmd+I）。在提示前固定文件：点击回形针图标，添加 design/CONTEXT.md、design/tokens.json 和 design/screens/home.json。然后提示：

实现 ./design/screens/home.json 中的主屏幕。

约束：
- 目标框架和组件规范在 ./design/CONTEXT.md 中
- 所有间距、颜色和圆角值必须来自 ./design/tokens.json
- UI 字符串必须使用 ./design/strings.json 中的键
- 根节点是垂直 stack。子节点在 JSON 中按顺序声明。
- 不要发明 Token 或 IR 文件中不存在的任何值。

Cursor 会读取固定的文件，将 IR 节点映射到你框架的基元，并生成实现。输出是 Token 引用的——如果你检查生成的代码，每个间距值都应该可以追溯到 tokens.json 中的一个键。

第五步：审查和迭代

将 design/screens/home.png 与渲染输出并排对比。PNG 是 Figma 的 2× 导出——它精确显示了设计应该是什么样子。差异是有意义的：它们指向 IR 映射缺口或未应用的 Token 值。

常见问题和后续提示：

Token 偏移——Agent 使用了硬编码的十六进制而非 Token：

将生成组件中的每个颜色值与 ./design/tokens.json 对比。
列出与 Token 键不匹配的颜色。用正确的 Token 引用替换它们。

缺少组件——IR 引用了 Agent 无法解析的组件 ID：

IR 引用了 componentId "btn-primary-01"。检查 ./design/components/inventory.json
获取其名称和类型，然后用该名称和正确的 Token 值实现一个占位符。

布局偏差——间距或对齐与 PNG 不符：

标题和卡片列表之间的垂直间距应该是 tokens.json 中的 spacing.24（24dp）。
你的输出使用了 16px。请修复。

哪些有效，哪些无效

效果良好：具有 stack 布局的平坦屏幕、Token 驱动的间距和颜色、带字符串引用的文本、简单的卡片和列表模式。一旦 IR 在上下文中，Cursor 处理这些效果很好——它停止猜测，开始映射。

效果较差：复杂的绝对定位叠加层（Cursor 有时会误读偏移坐标）、渐变填充（在 _meta.json 中标记为警告——Cursor 会近似处理）和矢量图标（IR 只存储引用 ID，不存储路径数据）。

纯截图与包对比：纯截图方式启动更快但不确定。每个会话都从头开始。模型可能一次搞对间距，下一轮又搞错。包在整个会话中可引用——Cursor 可以随时对照 Token 文件检查自己的输出，无需重新上传任何东西。

提示：在提示前检查 _meta.json 警告

在第一个实现提示前，读取 design/_meta.json。warnings 数组列出了导出器无法完全解析的内容：渐变填充、缺失的 Token 映射、带嵌入图片的框架。在提示中注明这些内容，这样 Agent 就不会尝试实现它们并静默回退到硬编码值。

cat design/_meta.json | python3 -m json.tool | grep -A 20 '"warnings"'

如果输出显示特定节点上有 "gradientFill: not fully supported"，告诉 Cursor 跳过该节点的背景，留下 // TODO: gradient 注释。

总结

工作流是：一次导出，随处引用。包是一个稳定的、机器可读的规范，Cursor 可以在多轮对话中参考，无需重新处理设计。你得到的是 Token 精准、字符串引用、布局正确的代码，而不是截图近似——当某些内容偏移时，你可以用一行提示词将 Agent 指向真相来源。

在 figmascope.dev 上亲自试试——粘贴你的 Figma URL，点击"导出 Agent 上下文"，不到两分钟就能将包解压到 Cursor 工作区。