figma-analyzer

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

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