Figma 导出至 Claude Code — Anthropic CLI 的结构化设计上下文

当组件清单是共享的时，"不要重新实现已存在的组件"这条指令至关重要。Claude Code 可以读取 design/components/inventory.json，识别哪些组件已经实现，并直接导入而非重新生成。

接入设计 token

figmascope 导出的 tokens.json 使用带有 $value 和 $type 字段的 W3C 风格嵌套结构：

{
  "color": {
    "surface":    { "$value": "#f6f2ea", "$type": "color" },
    "ink":        { "$value": "#1f1d1a", "$type": "color" },
    "accent":     { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    }
  }
}

在实现任何屏幕之前，先让 Claude Code 从这个文件生成 tailwind.config.ts 的 theme extension 配置块。这样所有后续屏幕实现都能一致地使用 Tailwind token 别名：

claude --print "Read design/tokens.json and generate a tailwind.config.ts
theme.extend block. Map color tokens to theme.extend.colors,
spacing tokens to theme.extend.spacing, and typography to
theme.extend.fontFamily / fontSize. Output only the config object."

token 格式以及 figmascope 在 Figma Variables 未配置时使用的频率推断回退机制，请参阅 AI Agent 的设计 Token 导出 进行深度了解。

处理字符串层

Figma 文件中的每个文本节点都会在 strings.json 中占有一个位置。键名使用从帧层级派生的点分隔命名：

{
  "home.hero.title":        "Everything you need",
  "home.hero.subtitle":    "Ship faster with structured context",
  "home.cta.primary":      "Get started",
  "settings.account.heading": "Account settings"
}

指示 Claude Code 将这些键作为 i18n 标识符使用。生成的组件不是在 JSX 中硬编码字符串 "Everything you need"，而是调用 t('home.hero.title')（或你的 i18n 库的等效方法）。资源文件已在 strings.json 中——你只需导入它或接入你的 i18n 设置。

如果 figmascope 检测到冲突——两个节点散列到相同的键——它会在 _meta.json 中发出 strings-collision 警告，并追加数字后缀以消歧。在开始会话前检查 _meta.json，了解可能的情况。

集成 CLAUDE.md

如果你使用 CLAUDE.md 项目上下文文件，添加一个简短的章节指向设计目录。这与 AI 设计交付 中描述的方法相互补充，也与 figmascope 与 Figma inspector 插件的区别 相呼应。

添加如下设计章节：

## Design context

Design tokens, layout IR, reference renders, and strings live in `design/`.
Always read `design/CONTEXT.md` before implementing any screen.
Token values are in `design/tokens.json` — never hardcode color or spacing.
Component canonical names are in `design/components/inventory.json`.

这样，项目中的每个 Claude Code 会话都会自动将设计上下文纳入工作知识，无需在每次提示中重复说明。

agent 真正能做到的事

有了结构化上下文，Claude Code 能可靠地做到：

• 间距值——因为 tokens.json 中有 spacing.4 → 16px，而不是从截图中目测
• 颜色——精确的十六进制值，而不是"看起来像暖橙色"
• 排版——字体族、大小、字重、行高，全部带类型
• 布局方向——stack 节点有明确的 direction 和 gap 字段
• 组件命名——inventory.json 是规范来源，不会出现凭空捏造的名称
• 文案——strings.json 防止 agent 改写或编造占位文本

仍然需要人工审查的内容：静态 Figma 帧中不可见的交互状态（悬停、聚焦、激活）、动画时序，以及文件中未明确设计的响应式断点。IR 捕获的是静态布局；动态行为超出范围。

在受控环境中使用 --dangerously-skip-permissions

对于希望 Claude Code 无需交互审批即可运行的自动化流水线——例如在设计更新后生成组件桩文件的 CI 步骤——可以使用 --dangerously-skip-permissions。仅适用于无生产凭据的沙箱环境。

claude --dangerously-skip-permissions --print "$(cat <<'EOF'
Read design/CONTEXT.md. Generate component stub files for any components
in design/components/inventory.json that don't already exist in src/components/.
Use TypeScript + React functional component format. Include a TODO comment
for each component referencing the relevant screen JSON.
EOF
)"

在生产开发者工作流中，保持权限交互式。这些提示存在有其合理性——Claude Code 可以且会写入文件，你需要在它执行前知道是哪些文件。

提示前检查导出警告

figmascope 会将可能影响输出质量的情况作为警告写入 _meta.json。在启动 Claude Code 会话前先检查：

python3 -c "
import json
meta = json.load(open('design/_meta.json'))
for w in meta.get('warnings', []):
    print(f\"{w['code']}: {w['message']}\")
print(f\"Frames exported: {meta['frameCount']}\")
print(f\"Tokens source: {meta.get('tokensSource', 'variables')}\")
"

需要重点关注的两个警告：

• layout-mode-none-inferred — 某个帧没有设置自动布局。figmascope 从子节点的绝对位置推断了布局，可靠性较低。在提示中标注相关屏幕："这个屏幕使用绝对定位，请相应生成。"
• strings-collision — 两个文本节点产生了相同的资源键。figmascope 用数字后缀消歧，但在 agent 生成 i18n 调用之前，你应该验证 strings.json 中的字符串是否正确。

Android 和 iOS 工作流

Claude Code 不局限于 Web 框架。上下文 bundle 与框架无关——布局 IR 和 token 都是数据，不是 CSS。以 Jetpack Compose 为例：

claude --print "$(cat <<'EOF'
Read design/CONTEXT.md and design/tokens.json.

Implement design/screens/Home.json as a Jetpack Compose screen.
- Map color tokens to a MaterialTheme ColorScheme
- Map spacing tokens to Dp values (strip 'px' suffix, use .dp)
- Map typography tokens to MaterialTheme.typography
- Use the component names from design/components/inventory.json as Composable names
- Reference design/screens/Home.png for visual accuracy
EOF
)"

IR 中的 stack 节点自然映射到 Compose 中的 Column（direction: vertical）和 Row（direction: horizontal）。type: "text" 的 leaf 节点变成 Text 可组合项；type: "image" 变成 Image 或占位符。完整模式请参阅 Jetpack Compose from Figma。

对设计 bundle 进行版本管理

将 design/ 目录视为项目的任何其他依赖项。当设计有重大变更时，从 figmascope.dev 重新导出，提交，并在 PR 中记录变更：

# Check when the bundle was last exported vs when Figma file was last modified
python3 -c "
import json
from datetime import datetime
meta = json.load(open('design/_meta.json'))
exported = datetime.fromisoformat(meta['exportedAt'].replace('Z', '+00:00'))
modified = datetime.fromisoformat(meta['figmaLastModified'].replace('Z', '+00:00'))
delta = modified - exported
if delta.total_seconds() > 0:
    print(f'WARNING: Figma file was modified {delta} after last export')
else:
    print('Bundle is current')
"

bundle 过时意味着 agent 正在基于过期的设计工作。时间戳检查能在你花时间进行基于过时规格的代码生成会话之前发现这个问题。