Claude Code + Figma — 确定性设计交付流水线

截图提示有其上限。你粘贴设计图，模型做出似乎合理的近似，你纠正它，下一轮它又偏离了。没有任何东西是锚定的。模型在两轮对话之间没有可以自我校验的真相来源。

figmascope 的上下文包改变了这一契约。你得到的不是每次都需要模型重新解读的像素参考，而是一套结构化、可引用的文件——设计 Token、布局 IR、组件清单、UI 字符串——这些文件在整个会话中保持一致。Claude Code 可以读取它们、基于它们实现功能，并按需对照这些文件检查自己的输出。

本指南涵盖从包导出到经过审查的 Token 验证实现的完整流程。

确定性的来源

以下三点使包可引用而非可解读：

Token 有类型和键名。tokens.json 将语义名称（spacing.16、color.7f5cfe）映射到精确值。模型无需重新处理设计就能对照文件检查其输出。
IR 是树结构，不是像素。screens/home.json 以 stack/overlay/absolute/leaf 节点描述布局——与实现目标（Compose、React 等）使用的抽象完全一致。没有视觉解读步骤。
包在多轮对话中保持稳定。一旦放入仓库，会话中的每个提示都可以引用相同的文件。Token 偏移是可检测的：让模型将其输出与 tokens.json 进行对比，它可以机械地完成这一操作。

第一步：生成包

在浏览器中打开 figmascope.dev，粘贴你的 Figma 文件 URL。导出程序在客户端运行，使用 Figma REST API——你的 Figma 个人访问令牌存储在 localStorage 中，不会发送到 figmascope 服务器。

点击导出 Agent 上下文。页面导出顶层框架、解析设计 Token、构建 IR，并下载 context-bundle.zip。

第二步：解压到项目目录

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

# 确认文件结构
find design/ -type f | sort
# design/CONTEXT.md
# design/_meta.json
# design/components/inventory.json
# design/screens/home.json
# design/screens/home.png
# design/screens/settings.json
# design/screens/settings.png
# design/strings.json
# design/tokens.json

目录名无关紧要——design/ 只是一个约定。关键在于 Claude Code 能从工作目录读取这些文件。

第三步：在仓库中启动 Claude Code

cd my-app
claude

Claude Code 在仓库根目录启动，拥有完整的文件访问权限。它可以在整个会话中读取、写入和引用目录树中的任何文件——这是使包模式发挥作用的关键能力。

第四步：定向 Agent

在任何实现之前，先发出一个阅读提示。这会将规范加载到会话上下文中，让你在编写任何代码前验证导出是否正确。

读取 ./design/CONTEXT.md 并告诉我：
1. 这个包的目标框架是什么？
2. 它引用了哪些 Token 文件？
3. 在实现之前，有什么警告需要了解？

Claude 会报告目标（默认为 Jetpack Compose）、Token 来源，以及 CONTEXT.md 头部中的任何警告——渐变填充、缺失的 Token 映射、不受支持的效果。你现在捕获这些问题，而不是在生成 200 行代码之后。

然后快速检查 Token：

列出 ./design/tokens.json 中的前 10 个颜色 Token。
然后列出间距 Token。

这确认了 Token 文件解析正确，并在实现前给你一个对调色板的心理模型。

第五步：实现屏幕

现在是实现提示词。明确说明哪些文件对哪些决策具有权威性：

将 ./design/screens/home.json 实现为 Jetpack Compose 屏幕。

规则：
- 应用 CONTEXT.md 约束。如果你还没有读取，请先读取。
- 所有间距、颜色和圆角值必须来自 ./design/tokens.json。
  将 Token 键映射到适当的 Compose 基元（例如 spacing.16 → 16.dp）。
- UI 字符串必须使用 ./design/strings.json 中的键，通过 stringResource() 调用。
  如果还没有资源 ID，使用 "fallback" 字段的值作为兜底。
- IR 节点类型映射如下：
    stack (axis:vertical)   → Column
    stack (axis:horizontal) → Row
    overlay                 → Box
    absolute                → Box with Modifier.offset
    leaf (text)             → Text with TextStyle
    leaf (rectangle)        → Box with Modifier.background
- 不要发明 Token 或 IR 文件中不存在的任何值。
  如果缺少某个值，留下带有预期 Token 键的 TODO 注释。

Claude Code 会读取 IR，遍历节点树，将每个节点映射到其 Compose 基元，并按键提取 Token 值。输出是可追溯的：每个 .dp 值都应对应一个间距 Token，每个 Color(0xFF...) 都应匹配一个颜色 Token。

第六步：检测并修复 Token 偏移

第一次实现完成后，在视觉审查之前先进行偏移检查。这是相比截图提示方式的关键优势——你可以让模型机械地验证自己的输出。

将生成的 HomeScreen.kt 中的每个颜色值与 ./design/tokens.json 进行对比。
列出输出中与颜色 Token 键不对应的十六进制值。
对每一个找出正确的 Token 并替换硬编码值。

对间距做同样的检查：

将 HomeScreen.kt 中的每个 .dp 值与 ./design/tokens.json 中的间距 Token 对比。
标记所有与间距 Token 不匹配的值。用正确的 Token 引用替换。

这个循环——实现、检查偏移、修复——收敛很快。经过两三次迭代后，输出就完全使用 Token 引用了。

提示：在第一个提示中包含 `_meta.json` 警告

design/_meta.json 包含一个 warnings 数组。这些是导出器无法完全解析的内容：渐变填充、嵌入图片、没有 Token 对应的效果。在实现前先读取：

cat design/_meta.json

如果输出中包含如下内容：

{
  "warnings": [
    "node 'hero-background': gradientFill not fully supported — background fill omitted",
    "node 'avatar': imageFill — reference only, no pixel data"
  ]
}

在实现提示词中明确说明："跳过英雄背景填充，留下 // TODO: gradient。对于 avatar 节点，使用灰色背景的占位 AsyncImage。"

这防止 Claude 静默近似——它会按你的指示操作，而不是自行猜测。

为什么这优于截图提示

多轮对话安全。Token 文件和 IR 在多轮对话间不会改变。你可以在第 12 轮问"你对卡片内边距使用了正确的间距吗？"，得到准确的答案，因为真相来源仍在磁盘上。

差异友好。当设计变更后重新导出时，新包与旧包产生差异。你可以让 Claude 审查差异并只更新受影响的组件——无需完整重新实现。

无需重复上传。包存储在仓库中。你不需要为每个新屏幕重新粘贴截图。每个新屏幕就是 design/screens/<name>.json——在下一个提示中再引用一个文件即可。

对缺口诚实。CONTEXT.md 和 _meta.json 明确列出了包未涵盖的内容。截图提示没有等价物——模型只是通过猜测填补缺口。

figmascope 主应用在浏览器中处理导出——粘贴你的 Figma URL，导出包，你就可以针对确定性规范运行 Claude Code 了。