name: figma-analyzer description: 使用Figma REST API从Figma提取设计资产和元数据。支持将框架/组件导出为图像，提取节点元数据、设计令牌和文件结构。与ai-multimodal技能集成以进行全面的UI研究。 license: MIT allowed-tools:

Bash
Read
Write

Figma分析器技能

使用Figma REST API从Figma文件中提取设计资产、元数据和规范。

核心能力

资产导出

将框架/组件导出为PNG、JPG、SVG、PDF格式
可配置缩放比例（1x、2x、3x、4x）
批量导出多个节点
下载图像到本地文件系统

元数据提取

文件结构和页面层次结构
节点属性（大小、位置、约束）
组件和样式定义
版本历史

设计令牌提取

颜色样式和调色板
排版样式
效果样式（阴影、模糊）
网格和布局样式

先决条件

API密钥设置

获取Figma个人访问令牌：

前往Figma设置 > 账户
滚动到“个人访问令牌”
生成具有读取权限的新令牌

技能按以下顺序检查FIGMA_ACCESS_TOKEN：

进程环境：export FIGMA_ACCESS_TOKEN="your-token"
项目根目录：.env
.claude/.env
.claude/skills/.env
.claude/skills/figma-analyzer/.env

安装依赖

pip install requests python-dotenv

Figma URL解析

Figma URL包含文件密钥和可选的节点ID：

https://www.figma.com/file/{file_key}/{file_name}?node-id={node_id}
https://www.figma.com/design/{file_key}/{file_name}?node-id={node_id}

示例：

完整文件：https://www.figma.com/file/ABC123/MyDesign
特定框架：https://www.figma.com/file/ABC123/MyDesign?node-id=1-234

快速开始

导出设计为图像

python scripts/figma_export.py \
  --url "https://www.figma.com/file/ABC123/Design?node-id=1-234" \
  --output docs/research/ui/design.png \
  --scale 2

获取文件元数据

python scripts/figma_export.py \
  --url "https://www.figma.com/file/ABC123/Design" \
  --metadata-only \
  --output docs/research/ui/figma-metadata.json

提取设计令牌

python scripts/figma_export.py \
  --url "https://www.figma.com/file/ABC123/Design" \
  --extract-tokens \
  --output docs/research/ui/design-tokens.json

批量导出多个框架

python scripts/figma_export.py \
  --url "https://www.figma.com/file/ABC123/Design" \
  --node-ids "1-234,1-235,1-236" \
  --output docs/research/ui/frames/ \
  --scale 2

API参考

使用的端点

端点	用途
GET /v1/files/:key	获取文件元数据和结构
GET /v1/files/:key/nodes	获取特定节点数据
GET /v1/images/:key	将节点导出为图像
GET /v1/files/:key/styles	获取已发布的样式
GET /v1/files/:key/components	获取已发布的组件

速率限制

免费层级：每分钟300个请求
付费层级：根据计划有更高限制
实施指数退避进行重试

输出格式

元数据JSON结构

{
  "file_key": "ABC123",
  "name": "我的设计",
  "last_modified": "2024-01-15T10:30:00Z",
  "thumbnail_url": "https://...",
  "nodes": {
    "1-234": {
      "name": "英雄部分",
      "type": "FRAME",
      "absoluteBoundingBox": {
        "x": 0, "y": 0,
        "width": 1440, "height": 800
      },
      "children": [...]
    }
  }
}

设计令牌JSON结构

{
  "colors": {
    "primary": {"value": "#3B82F6", "name": "蓝色 500"},
    "secondary": {"value": "#10B981", "name": "绿色 500"}
  },
  "typography": {
    "heading-1": {
      "fontFamily": "Inter",
      "fontSize": 48,
      "fontWeight": 700,
      "lineHeight": 1.2
    }
  },
  "effects": {
    "shadow-md": {
      "type": "DROP_SHADOW",
      "offset": {"x": 0, "y": 4},
      "radius": 6,
      "color": "rgba(0,0,0,0.1)"
    }
  },
  "spacing": {
    "xs": 4, "sm": 8, "md": 16, "lg": 24, "xl": 32
  }
}

与ai-multimodal集成

导出图像后，使用ai-multimodal进行视觉分析：

# 步骤1：从Figma导出
python .claude/skills/figma-analyzer/scripts/figma_export.py \
  --url "$FIGMA_URL" \
  --output docs/research/ui/design.png \
  --scale 2

# 步骤2：使用Gemini Vision分析
python .claude/skills/ai-multimodal/scripts/gemini_batch_process.py \
  --files docs/research/ui/design.png \
  --task analyze \
  --prompt "分析布局并提取组件规范" \
  --output docs/research/ui/analysis.md \
  --model gemini-2.5-flash

错误处理

错误代码	含义	解决方案
400	错误请求	检查URL格式和节点ID
403	禁止访问	验证访问令牌和文件权限
404	未找到	检查文件密钥和节点ID是否存在
429	速率限制	实施退避，等待并重试
500	服务器错误	使用指数退避重试

最佳实践

图像导出

使用2倍缩放进行高质量分析
导出特定框架，而非整个文件
使用PNG处理具有透明度的UI元素
使用JPG处理照片密集型设计

令牌提取

确保样式在Figma中已发布
使用一致的命名约定
导出本地和已发布的样式
将令牌映射到CSS自定义属性

性能

缓存元数据以减少API调用
批量导出多个节点
对大文件使用节点ID过滤
实施请求限流

工作流集成

此技能设计用于与以下配合：

ui-researcher agent：UI研究工作流的主要消费者
ai-multimodal skill：用于导出图像的视觉分析
/ui-research command：协调完整的研究工作流

脚本概述

figma_export.py

用于Figma API交互的主要脚本：

python scripts/figma_export.py --help

选项：
  --url          Figma文件或框架URL（必需）
  --output       图像/数据的输出路径
  --scale        导出缩放比例（1, 2, 3, 4）
  --format       导出格式（png, jpg, svg, pdf）
  --node-ids     逗号分隔的节点ID以导出
  --metadata-only  仅获取元数据，无图像导出
  --extract-tokens 提取设计令牌
  --verbose      启用详细输出

Figma分析器Skill figma-analyzer