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

```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)