← スキル一覧に戻る
figma-analyzer
Junior-Frontend-dev / Hi-u-ng
⭐ 0🍴 0📅 2026年1月16日
Extract design assets and metadata from Figma using the Figma REST API.
SKILL.md
---
name: figma-analyzer
description: Extract design assets and metadata from Figma using the Figma REST API.
Supports exporting frames/components as images, extracting node metadata, design
tokens, and file structure. Use with ai-multimodal skill for comprehensive UI research.
license: MIT
allowed-tools:
- Bash
- Read
- Write
---
# Figma Analyzer Skill
Extract design assets, metadata, and specifications from Figma files using the Figma REST API.
## Core Capabilities
### Asset Export
- Export frames/components as PNG, JPG, SVG, PDF
- Configurable scale (1x, 2x, 3x, 4x)
- Batch export multiple nodes
- Download images to local filesystem
### Metadata Extraction
- File structure and page hierarchy
- Node properties (size, position, constraints)
- Component and style definitions
- Version history
### Design Token Extraction
- Color styles and palettes
- Typography styles
- Effect styles (shadows, blurs)
- Grid and layout styles
## Prerequisites
### API Key Setup
Obtain a Figma Personal Access Token:
1. Go to Figma Settings > Account
2. Scroll to "Personal access tokens"
3. Generate a new token with read permissions
The skill checks for `FIGMA_ACCESS_TOKEN` in this order:
1. Process environment: `export FIGMA_ACCESS_TOKEN="your-token"`
2. Project root: `.env`
3. `.claude/.env`
4. `.claude/skills/.env`
5. `.claude/skills/figma-analyzer/.env`
### Install Dependencies
```bash
pip install requests python-dotenv
```
## Figma URL Parsing
Figma URLs contain the file key and optional node 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}
```
Examples:
- Full file: `https://www.figma.com/file/ABC123/MyDesign`
- Specific frame: `https://www.figma.com/file/ABC123/MyDesign?node-id=1-234`
## Quick Start
### Export Design as Image
```bash
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
```
### Get File Metadata
```bash
python scripts/figma_export.py \
--url "https://www.figma.com/file/ABC123/Design" \
--metadata-only \
--output docs/research/ui/figma-metadata.json
```
### Extract Design Tokens
```bash
python scripts/figma_export.py \
--url "https://www.figma.com/file/ABC123/Design" \
--extract-tokens \
--output docs/research/ui/design-tokens.json
```
### Batch Export Multiple Frames
```bash
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 Reference
### Endpoints Used
| Endpoint | Purpose |
|----------|---------|
| GET /v1/files/:key | Get file metadata and structure |
| GET /v1/files/:key/nodes | Get specific node data |
| GET /v1/images/:key | Export nodes as images |
| GET /v1/files/:key/styles | Get published styles |
| GET /v1/files/:key/components | Get published components |
### Rate Limits
- **Free tier**: 300 requests/minute
- **Paid tier**: Higher limits based on plan
- Implement exponential backoff for retries
## Output Formats
### Metadata JSON Structure
```json
{
"file_key": "ABC123",
"name": "My Design",
"last_modified": "2024-01-15T10:30:00Z",
"thumbnail_url": "https://...",
"nodes": {
"1-234": {
"name": "Hero Section",
"type": "FRAME",
"absoluteBoundingBox": {
"x": 0, "y": 0,
"width": 1440, "height": 800
},
"children": [...]
}
}
}
```
### Design Tokens JSON Structure
```json
{
"colors": {
"primary": {"value": "#3B82F6", "name": "Blue 500"},
"secondary": {"value": "#10B981", "name": "Green 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
}
}
```
## Integration with ai-multimodal
After exporting images, use ai-multimodal for visual analysis:
```bash
# Step 1: Export from Figma
python .claude/skills/figma-analyzer/scripts/figma_export.py \
--url "$FIGMA_URL" \
--output docs/research/ui/design.png \
--scale 2
# Step 2: Analyze with Gemini Vision
python .claude/skills/ai-multimodal/scripts/gemini_batch_process.py \
--files docs/research/ui/design.png \
--task analyze \
--prompt "Analyze layout and extract component specifications" \
--output docs/research/ui/analysis.md \
--model gemini-2.5-flash
```
## Error Handling
| Error Code | Meaning | Resolution |
|------------|---------|------------|
| 400 | Bad request | Check URL format and node IDs |
| 403 | Forbidden | Verify access token and file permissions |
| 404 | Not found | Check file key and node ID exist |
| 429 | Rate limited | Implement backoff, wait and retry |
| 500 | Server error | Retry with exponential backoff |
## Best Practices
### Image Export
1. Use 2x scale for high-quality analysis
2. Export specific frames, not entire files
3. Use PNG for UI elements with transparency
4. Use JPG for photo-heavy designs
### Token Extraction
1. Ensure styles are published in Figma
2. Use consistent naming conventions
3. Export both local and published styles
4. Map tokens to CSS custom properties
### Performance
1. Cache metadata to reduce API calls
2. Batch export multiple nodes at once
3. Use node-id filtering for large files
4. Implement request throttling
## Workflow Integration
This skill is designed to work with:
- **ui-researcher agent**: Primary consumer for UI research workflows
- **ai-multimodal skill**: For visual analysis of exported images
- **/ui-research command**: Orchestrates the full research workflow
## Scripts Overview
### figma_export.py
Main script for Figma API interaction:
```bash
python scripts/figma_export.py --help
Options:
--url Figma file or frame URL (required)
--output Output path for images/data
--scale Export scale (1, 2, 3, 4)
--format Export format (png, jpg, svg, pdf)
--node-ids Comma-separated node IDs to export
--metadata-only Only fetch metadata, no image export
--extract-tokens Extract design tokens
--verbose Enable verbose output
```
## Resources
- [Figma REST API Documentation](https://www.figma.com/developers/api)
- [Figma Access Tokens](https://www.figma.com/developers/api#access-tokens)
- [Figma Node Types](https://www.figma.com/developers/api#node-types)