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:
- •Go to Figma Settings > Account
- •Scroll to "Personal access tokens"
- •Generate a new token with read permissions
The skill checks for FIGMA_ACCESS_TOKEN in this order:
- •Process environment:
export FIGMA_ACCESS_TOKEN="your-token" - •Project root:
.env - •
.claude/.env - •
.claude/skills/.env - •
.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:
code
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
- •Use 2x scale for high-quality analysis
- •Export specific frames, not entire files
- •Use PNG for UI elements with transparency
- •Use JPG for photo-heavy designs
Token Extraction
- •Ensure styles are published in Figma
- •Use consistent naming conventions
- •Export both local and published styles
- •Map tokens to CSS custom properties
Performance
- •Cache metadata to reduce API calls
- •Batch export multiple nodes at once
- •Use node-id filtering for large files
- •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