ingest-figma

导入 Figma

使用 REST API 从 Figma 文件中提取设计系统。如果没有令牌，则回退到从 SVG 导入。

预检

1. Bash(test -n "$FIGMA_TOKEN" && echo has-token || echo no-token) — 检查环境变量
2. 如果是 no-token：
   • 告诉用户："未找到 FIGMA_TOKEN。有两个选项：（a）在 https://www.figma.com/developers/api#access-tokens 获取令牌，并在 shell 中执行 export FIGMA_TOKEN=...；或者（b）在 Figma 中将画框导出为 SVG（右键点击画框 → Copy as → Copy as SVG），然后将文件粘贴到 artifacts/ingested/ — 我会解析 SVG。"
   • 停止；等待用户回复。

解析 URL

Figma URL 格式：https://www.figma.com/(file|design|proto)/<fileKey>/<name>?node-id=<nodeId>

提取：

• fileKey — /file/ 或 /design/ 后的字母数字字符串
• nodeId — 查询参数 node-id（URL 解码后，通常包含 :）

步骤（令牌路径）

1. 获取文件节点：

   Bash(curl -H "X-FIGMA-TOKEN: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/<fileKey>/nodes?ids=<nodeId>&depth=2" \
     -o /tmp/figma-<ts>.json)
   

2. 获取样式定义：

   Bash(curl -H "X-FIGMA-TOKEN: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/<fileKey>/styles" \
     -o /tmp/figma-styles-<ts>.json)
   

3. 解析 JSON：

   • 颜色：遍历 document.children → 查找 fills 中 type === 'SOLID' 的项 → 提取 color {r,g,b} → 转换为十六进制
   • 效果（阴影）：查找 effects 中 type === 'DROP_SHADOW' 的项
   • 文本样式：查找包含 fontFamily、fontSize、fontWeight、lineHeightPx 的 style
   • 组件：遍历查找 type === 'COMPONENT' 和 type === 'COMPONENT_SET'
   • 本地样式：/styles 返回的样式端点会返回具名变量

4. 写入：

   artifacts/ingested/figma-<fileKey>-tokens.json
   

   使用与 ingest-github 相同的架构，并添加 "source": { "figma_url": "...", "file_key": "...", "node_id": "..." }。

5. 提供下一步：

   • "已从 Figma 中提取 X 种颜色、Y 种文本样式和 Z 个组件。已保存到 artifacts/ingested/figma-<fileKey>-tokens.json。"
   • 继续使用 /create-design-system，或启动 artifact 技能。

步骤（SVG 回退路径）

1. 用户将 SVG 文件放入 artifacts/ingested/
2. Read SVG 内容
3. 提取 fill="#..." / stroke="#..." / style="...color..." 属性
4. 识别 <text> 元素以获取字体信息（font-family、font-size、font-weight）
5. 构建部分 tokens.json，并添加 "source": { "svg": "<path>" } 和置信度标记
6. 注意：SVG 导出会丢失组件结构，只保留视觉图元

速率限制

Figma API：免费套餐每分钟 50 次请求。获取一个画框和样式只需 2 次请求，远低于限制。

安全

FIGMA_TOKEN 仅保存在环境变量中——绝不写入磁盘或记录到日志。