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:

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

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

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:

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

figma-analyzer

Install Skill

SKILL.md