figma-analyzer

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

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

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

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

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

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

{
  "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

{
  "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:

# 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:

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
• Figma Access Tokens
• Figma Node Types