Figma 导出至 Cursor — 为 Cursor AI 导出设计上下文

Cursor 的 AI 可以编写大量 UI 代码。但它无法读取你的 Figma 文件。你粘贴一张截图，它只能靠猜——间距不对、颜色值错误、组件名凭空捏造。问题不在模型本身，而在于缺少结构化上下文。

figmascope 正是为此而生。它将 Figma 文件导出为一个 zip bundle——设计 token、逐屏布局树、参考渲染图、组件清单、UI 字符串——语言模型生成精准代码（而非似是而非的代码）所需的一切。主应用完全在浏览器中运行，无需后端，无需上传。

本文介绍从 Figma URL 到 Cursor 代码生成的完整工作流程。如果你使用 Claude Code 而非 Cursor，请参阅 Figma 导出至 Claude Code 了解 Claude 专属工作流。若想全面了解什么样的交付物才算 agent 就绪，请参阅 AI 设计交付。

上下文 bundle 包含哪些内容

对 Figma 文件运行 figmascope 后，你会得到一个 .zip，其中包含：

CONTEXT.md — 一份为 agent 优先阅读而撰写的规格文档。它列举约束条件、范围说明、版本注释，以及从文件本身推导出的工作示例。
tokens.json — 带类型的设计 token（颜色、间距、圆角、排版），采用 W3C 风格的嵌套结构。优先从 Figma Variables 获取；若未设置，则通过使用频率推断。
screens/*.json — 逐屏中间表示。每个节点均有类型（stack、overlay、absolute 或 leaf），保留空间信息，并交叉引用至 token。
screens/*.png — 2× 参考渲染图，用于视觉基准验证。
components/inventory.json — 文件中每个组件的 { id, name, type }。
strings.json — 所有 UI 字符串，汇总整理，配有点分隔资源键（onboarding.welcome.title）。
_meta.json — 构建清单：时间戳、fileKey、帧数量及所有警告信息。

没有任何数据被上传。你的 Personal Access Token 仅存在于浏览器内存中，且只发送至 api.figma.com。zip 文件在客户端组装完成后直接由浏览器下载。

第一步 — 获取 Figma Personal Access Token

前往 Figma → Account Settings → Personal Access Tokens，创建一个具有 File content: read-only 权限的 token。这是所需的最低权限。

该 token 永远不会离开你的浏览器会话；figmascope 仅将其作为 X-Figma-Token 请求头发送至 api.figma.com，不会发往其他任何地方。完整的威胁模型请参阅 PAT 安全性与 figmascope。

第二步 — 导出上下文 bundle

在浏览器中打开 figmascope.dev。
粘贴 Figma 文件 URL（例如 https://www.figma.com/file/ABC123/MyDesign）。
粘贴你的 Personal Access Token。
点击 Export Context Bundle。
一个 figmascope-<fileKey>.zip 文件将下载至你的本地机器。

将其解压至你的项目中。推荐放在仓库根目录的 design/ 文件夹下：

unzip figmascope-ABC123.zip -d design/
# → design/CONTEXT.md
# → design/tokens.json
# → design/screens/Home.json
# → design/screens/Home.png
# → design/components/inventory.json
# → design/strings.json
# → design/_meta.json

第三步 — 在 Cursor 中打开项目

像往常一样在 Cursor 中打开你的项目文件夹。design/ 目录现在已成为工作区的一部分，Cursor 的索引器会将其纳入索引。

在向模型发出提示之前，先自己读一遍 design/CONTEXT.md。它会告诉你哪些帧被导出、token 命名规则是什么，以及导出过程中发出的任何警告（例如 layout-mode-none-inferred，表示 Figma 未报告自动布局的帧）。这些警告与你的 agent 遇到的相同。

第四步 — 编写高效的 Cursor 提示词

最简单的起点是可以直接粘贴到 Cursor Chat 的参考提示词：

Read design/CONTEXT.md first, then implement the Home screen.

Use:
- design/tokens.json for all color, spacing, and typography values
- design/screens/Home.json for the layout tree
- design/screens/Home.png as the visual reference
- design/strings.json for all copy (use the resource keys as i18n identifiers)
- design/components/inventory.json to match component names

Target: React + Tailwind CSS. Map token values to Tailwind config entries rather
than hardcoding hex values. Use the component names from inventory.json as
component file names (PascalCase).

Cursor 的 Composer 会遵循 CONTEXT.md 中的约束，从 Home.json 查找布局树，从 tokens.json 提取间距，并生成匹配你设计系统的代码，而不是近似猜测。

模型不了解你的设计，它只知道你给它的内容。结构化 JSON 永远优于截图。

第五步 — 将 token 映射到框架配置

导出的 tokens.json 使用 W3C 风格的嵌套结构：

{
  "color": {
    "surface": { "$value": "#f6f2ea", "$type": "color" },
    "accent":  { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "4":  { "$value": "16px", "$type": "dimension" },
    "8":  { "$value": "32px", "$type": "dimension" }
  },
  "radius": {
    "sm": { "$value": "4px",  "$type": "dimension" },
    "md": { "$value": "8px",  "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "fontWeight": { "$value": 400,       "$type": "number" }
    }
  }
}

对于 Tailwind，可以让 Cursor 直接从 tokens.json 生成 tailwind.config.js 的 theme.extend 配置块。token 格式与频率推断的深度解析请参阅 AI Agent 的设计 Token 导出。token 结构扁平到足以用一个 Node 脚本完成遍历，如果你想自动化这个过程：

// scripts/tokens-to-tailwind.js
const tokens = require('../design/tokens.json');

const colors = Object.fromEntries(
  Object.entries(tokens.color).map(([k, v]) => [k, v.$value])
);
const spacing = Object.fromEntries(
  Object.entries(tokens.spacing).map(([k, v]) => [k, v.$value])
);

module.exports = { colors, spacing };

第六步 — 处理多屏项目

Figma 文件中的每个帧都会生成一个 screens/<FrameName>.json 和对应的 .png。对于有十几个屏幕的项目，建议逐步推进。Cursor Composer 每个会话处理一个屏幕效果最佳；使用 @file 引用明确指定屏幕的 JSON 和 PNG：

@design/screens/Settings.json
@design/screens/Settings.png

Implement the Settings screen. Follow the same component structure
as the Home screen already implemented. Use tokens from design/tokens.json.

组件清单（design/components/inventory.json）有助于避免跨屏的命名漂移——屏幕 JSON 中引用的每个组件在清单中都有规范的 id 和 name。如果你要生成共享组件库，应以这些名称为准。

IR 在实际中的样子

逐屏 JSON 使用递归节点结构。以下是一个卡片组件的简化示例：

{
  "kind": "stack",
  "name": "ProductCard",
  "direction": "vertical",
  "gap": { "$ref": "spacing.4" },
  "padding": { "top": 16, "right": 16, "bottom": 16, "left": 16 },
  "background": { "$ref": "color.surface" },
  "radius": { "$ref": "radius.md" },
  "children": [
    {
      "kind": "leaf",
      "name": "ProductImage",
      "type": "image",
      "width": 320,
      "height": 200
    },
    {
      "kind": "leaf",
      "name": "ProductTitle",
      "type": "text",
      "text": { "$ref": "strings.product.card.title" },
      "style": { "$ref": "typography.heading.sm" }
    }
  ]
}

Token 引用使用 $ref 字符串，与 tokens.json 中的键完全对应。模型无需额外查找步骤即可完成解析。完整节点 schema 文档请参阅逐屏 IR 详解。

保持上下文的时效性

设计文件会持续变化。一个好习惯：每当设计有重大修订时重新运行 figmascope，提交更新后的 design/ 文件夹，并在 PR 描述中记录版本信息。_meta.json 包含时间戳和 Figma 文件的 lastModified 字段，方便你对比 bundle 最后生成时间与文件最后修改时间。

// _meta.json
{
  "figmascopeVersion": "1.0.0",
  "fileKey": "ABC123",
  "exportedAt": "2026-05-11T09:14:00Z",
  "figmaLastModified": "2026-05-10T18:30:00Z",
  "frameCount": 12,
  "warnings": []
}

如果 warnings 不为空，请在将上下文交给 agent 之前先处理这些警告。常见警告：strings-collision（两个节点解析到相同的键）和 layout-mode-none-inferred（没有明确自动布局的容器，figmascope 从子节点位置推断了布局）。

常见 Cursor 工作流

基于差异的更新

当设计有小幅修改——比如卡片组件的间距从 spacing.4 改为 spacing.6——你可以让 Cursor 只应用差异，而无需重新生成整个屏幕：

The design/tokens.json was updated. spacing.4 is now 24px instead of 16px.
Find all components using spacing.4 and update them. Do not touch anything else.

之所以可行，是因为生成的组件以 Tailwind 类名（gap-spacing-4）引用 token 名称，而非原始像素值。token 变更就是查找替换，而不是重新设计。

向已有代码库添加新屏幕

在已实现了 1 到 N-1 个屏幕的代码库中添加第 N 个屏幕时，提示词的关键在于将 agent 锚定到已有组件库：

@design/screens/Checkout.json
@design/screens/Checkout.png

Implement the Checkout screen. Reuse existing components from src/components/
wherever the component name matches design/components/inventory.json.
Only create new component files for components not already implemented.
Use design/tokens.json for all token values.

组件清单是设计组件名称与代码库文件名之间的桥梁。没有它，agent 会凭空编造导入路径，创建重复组件。

生成设计系统基线

在实现任何屏幕之前，先用上下文 bundle 生成设计系统基线：token 配置、色板组件和基础排版样式。这将使所有后续屏幕实现锚定在同一基础上：

Read design/tokens.json and design/CONTEXT.md.

Generate:
1. tailwind.config.ts theme.extend block from all tokens
2. src/styles/tokens.css with CSS custom properties for the same tokens
3. src/components/foundations/ColorPalette.tsx showing all color tokens
4. src/styles/typography.css with the typography token classes

Name all classes and variables using the token key paths
(e.g. --color-accent, text-ink, bg-surface).

一旦基线确立，每次屏幕实现都可以引用它。agent 不会在每个会话中重新从设计推导颜色，而是直接使用已生成的类名。

需要提前了解的局限性

figmascope 的上下文 bundle 捕获的是静态结构。以下几类内容无法表示：

悬停和聚焦状态 — Figma 的交互组件和原型连接不包含在内。你需要在提示词中描述这些状态，或按惯例自行实现。
响应式断点 — IR 仅捕获一个视口（帧的尺寸）。多断点布局需要单独的帧或手动提示引导。
复杂动画 — Figma 的 Smart Animate 和过渡设置不会被提取。如果设计师创建了单独的帧，静态进入/退出状态会以独立帧的形式呈现。
非帧节点 — figmascope 处理 Figma 帧（顶层设计屏幕）。切片、作为页面直接子级的分组以及 Figma 章节会被过滤掉。

CONTEXT.md 文件会说明哪些帧被排除及原因，以便 agent 不会尝试实现那些故意排除在范围之外的内容。