---
name: figma-tools
description: Fetch and parse Figma design files for AI-assisted implementation. Extract layout, styles, components, and assets from Figma URLs.
---

# Figma Tools

Direct Figma API tools for fetching design data. Parse Figma files into simplified, AI-friendly structures.

## Setup

```bash
cd {baseDir}/figma-tools
pnpm install
```

Set your Figma access token:

```bash
export FIGMA_API_KEY="your-token-here"
```

Get a token from [Figma Settings → Personal Access Tokens](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens).

## Commands

### Get File or Node

```bash
# Get entire file
{figmaDir}/figma-tools get https://www.figma.com/file/ABC123/My-Design

# Get specific frame/node
{figmaDir}/figma-tools get "https://www.figma.com/file/ABC123/My-Design?node-id=123%3A456"

# Control depth (reduce token count)
{figmaDir}/figma-tools get https://www.figma.com/file/ABC123/My-Design --depth 2

# Output raw Figma API response
{figmaDir}/figma-tools get https://www.figma.com/file/ABC123/My-Design --raw > raw.json

# Output as YAML
{figmaDir}/figma-tools get https://www.figma.com/file/ABC123/My-Design --yaml
```

### Download Assets

```bash
# Download all images from a file
{figmaDir}/figma-tools download https://www.figma.com/file/ABC123/My-Design ./assets

# Download PNGs at 2x scale
{figmaDir}/figma-tools download https://www.figma.com/file/ABC123/My-Design ./assets --scale 2

# Download SVGs
{figmaDir}/figma-tools download https://www.figma.com/file/ABC123/My-Design ./icons --format svg
```

### Parse Local Files

```bash
# Simplify a raw Figma JSON file
{figmaDir}/figma-tools parse ./raw-figma-response.json

# Output to file
{figmaDir}/figma-tools parse ./raw.json --yaml > design.yaml
```

## When to Use

- **Implementing designs**: Fetch layout, colors, typography, spacing directly from Figma
- **Extracting assets**: Download PNGs/SVGs referenced in designs
- **Design-to-code**: Get structured data about components and styles
- **Auditing designs**: Programmatically analyze design systems

## URL Formats Supported

```
https://www.figma.com/file/{fileKey}/{title}
https://www.figma.com/file/{fileKey}/{title}?node-id={nodeId}
https://www.figma.com/design/{fileKey}/{title}
```

## Output Format

The simplified output transforms verbose Figma API responses into clean structures:

```typescript
{
  name: "My Design",
  lastModified: "2024-01-15T10:30:00Z",
  thumbnailUrl: "...",
  nodes: [{
    id: "123:456",
    name: "Button Primary",
    type: "FRAME",
    text: "Click me",
    textStyle: "style_001",
    fills: "fill_001",
    strokes: "stroke_001",
    effects: "effect_001",
    layout: "layout_001",
    borderRadius: "8px",
    opacity: 0.9,
    children: [...]
  }],
  components: {
    "component-123": { name: "Button", description: "..." }
  },
  globalVars: {
    styles: {
      "style_001": { fontFamily: "Inter", fontSize: 16, ... },
      "fill_001": [{ type: "SOLID", hex: "#FF5733" }],
      "layout_001": { mode: "row", gap: "8px", justifyContent: "center" }
    }
  }
}
```

## Efficiency Guide

### Use --depth to Limit Data

Figma files can be huge. Use `--depth` to fetch only what you need:

```bash
{figmaDir}/figma-tools get <url> --depth 1
{figmaDir}/figma-tools get <url> --depth 2
```

### Get Specific Nodes

```bash
{figmaDir}/figma-tools get "https://www.figma.com/file/ABC/My?node-id=123%3A456"
```

### Batch Asset Downloads

```bash
{figmaDir}/figma-tools download <url> ./assets --scale 2
```