@a5c-ai/figma-api

---
name: figma-api
description: Direct Figma API interactions for design asset management. Fetch files and components, extract design tokens, export images, manage comments, and access version history.
allowed-tools: Bash(*) Read Write Edit Glob Grep WebFetch
metadata:
  author: babysitter-sdk
  version: "1.0.0"
  category: design-integration
  backlog-id: SK-UX-002
---

# figma-api

You are **figma-api** - a specialized skill for direct Figma API interactions, enabling seamless design-to-code workflows and design asset management.

## Overview

This skill enables AI-powered Figma integration including:
- Fetching files, components, and component sets
- Extracting design tokens (colors, typography, spacing)
- Exporting images and assets at various scales
- Managing comments and feedback
- Accessing version history and change tracking
- Syncing design systems between Figma and code

## Prerequisites

- Figma Personal Access Token (PAT) or OAuth token
- Figma file/project access permissions
- Optional: MCP server for enhanced real-time integration

## Capabilities

### 1. File and Component Fetching

Retrieve Figma file data and components:

```javascript
// Fetch entire file
const fileData = await figmaApi.getFile(fileKey);

// Fetch specific nodes
const nodes = await figmaApi.getFileNodes(fileKey, ['1:2', '1:3']);

// Fetch component metadata
const components = await figmaApi.getComponents(fileKey);

// Fetch component sets (variants)
const componentSets = await figmaApi.getComponentSets(fileKey);
```

### 2. Design Token Extraction

Extract design tokens from Figma files:

```json
{
  "colors": {
    "primary": {
      "50": { "value": "#E3F2FD", "type": "color" },
      "100": { "value": "#BBDEFB", "type": "color" },
      "500": { "value": "#2196F3", "type": "color" },
      "900": { "value": "#0D47A1", "type": "color" }
    },
    "semantic": {
      "success": { "value": "{colors.green.500}", "type": "color" },
      "error": { "value": "{colors.red.500}", "type": "color" },
      "warning": { "value": "{colors.yellow.500}", "type": "color" }
    }
  },
  "typography": {
    "heading-1": {
      "fontFamily": { "value": "Inter", "type": "fontFamily" },
      "fontSize": { "value": "48px", "type": "dimension" },
      "fontWeight": { "value": "700", "type": "fontWeight" },
      "lineHeight": { "value": "1.2", "type": "number" }
    }
  },
  "spacing": {
    "xs": { "value": "4px", "type": "dimension" },
    "sm": { "value": "8px", "type": "dimension" },
    "md": { "value": "16px", "type": "dimension" },
    "lg": { "value": "24px", "type": "dimension" },
    "xl": { "value": "32px", "type": "dimension" }
  }
}
```

### 3. Image Export

Export images and assets at various scales:

```javascript
// Export specific nodes as PNG
const images = await figmaApi.getImage(fileKey, {
  ids: ['1:2', '1:3'],
  format: 'png',
  scale: 2
});

// Export as SVG
const svgImages = await figmaApi.getImage(fileKey, {
  ids: ['1:4'],
  format: 'svg',
  svg_include_id: true,
  svg_simplify_stroke: true
});

// Export with fills rendered
const renderedImages = await figmaApi.getImageFills(fileKey);
```

### 4. Comment Management

Manage design feedback and comments:

```javascript
// Get all comments
const comments = await figmaApi.getComments(fileKey);

// Post new comment
const newComment = await figmaApi.postComment(fileKey, {
  message: 'Please review the button states',
  client_meta: { x: 100, y: 200 }
});

// Reply to comment
const reply = await figmaApi.postComment(fileKey, {
  message: 'Updated per feedback',
  comment_id: '123456'
});

// Resolve comment
await figmaApi.deleteComment(fileKey, commentId);
```

### 5. Version History

Access file version history:

```javascript
// Get version history
const versions = await figmaApi.getVersions(fileKey);

// Output:
{
  "versions": [
    {
      "id": "123456789",
      "created_at": "2026-01-24T10:30:00Z",
      "label": "v2.0 - Updated color system",
      "description": "Migrated to new brand colors",
      "user": {
        "id": "user_id",
        "handle": "designer",
        "img_url": "avatar.png"
      }
    }
  ]
}
```

### 6. Style Extraction

Extract styles from Figma:

```javascript
// Get all styles
const styles = await figmaApi.getStyles(fileKey);

// Extract color styles
const colorStyles = styles.filter(s => s.style_type === 'FILL');

// Extract text styles
const textStyles = styles.filter(s => s.style_type === 'TEXT');

// Extract effect styles (shadows, blurs)
const effectStyles = styles.filter(s => s.style_type === 'EFFECT');
```

## MCP Server Integration

This skill can leverage the following MCP servers for enhanced capabilities:

| Server | Description | Installation |
|--------|-------------|--------------|
| Claude Talk to Figma MCP | Bidirectional Figma interaction for real-time design manipulation | [GitHub](https://github.com/arinspunk/claude-talk-to-figma-mcp) |
| Figma MCP Server (karthiks3000) | Claude MCP Server for working with Figma files | [GitHub](https://github.com/karthiks3000/figma-mcp-server) |
| html.to.design MCP | Converts HTML directly into editable Figma designs | [Docs](https://html.to.design/docs/mcp-tab/) |

## API Reference

### REST API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/files/:key` | GET | Get file data |
| `/v1/files/:key/nodes` | GET | Get specific nodes |
| `/v1/files/:key/images` | GET | Export images |
| `/v1/files/:key/comments` | GET/POST | Manage comments |
| `/v1/files/:key/versions` | GET | Get version history |
| `/v1/files/:key/components` | GET | Get components |

### Authentication

```bash
# Using Personal Access Token
curl -H "X-Figma-Token: YOUR_TOKEN" \
  "https://api.figma.com/v1/files/FILE_KEY"

# Using OAuth
curl -H "Authorization: Bearer OAUTH_TOKEN" \
  "https://api.figma.com/v1/files/FILE_KEY"
```

## Best Practices

1. **Cache responses** - Figma API has rate limits; cache file data locally
2. **Use node IDs** - Fetch specific nodes instead of entire files when possible
3. **Batch exports** - Group image exports to minimize API calls
4. **Handle pagination** - Large files may require paginated requests
5. **Version your tokens** - Use descriptive names and rotate tokens regularly
6. **Respect rate limits** - 50 requests per minute for personal access tokens

## Process Integration

This skill integrates with the following processes:
- `component-library.js` - Design-to-code component workflows
- `design-system.js` - Design system synchronization
- `hifi-prototyping.js` - High-fidelity prototype exports
- `wireframing.js` - Wireframe asset management

## Output Format

When executing operations, provide structured output:

```json
{
  "operation": "extract-tokens",
  "fileKey": "abc123xyz",
  "status": "success",
  "tokens": {
    "colors": {},
    "typography": {},
    "spacing": {}
  },
  "metadata": {
    "lastModified": "2026-01-24T10:30:00Z",
    "version": "123456789"
  },
  "artifacts": ["tokens.json", "tokens.css"]
}
```

## Error Handling

- Handle 403 errors for permission issues
- Retry on 429 rate limit errors with exponential backoff
- Validate file keys before making requests
- Provide helpful messages for common authentication failures

## Constraints

- Respect Figma API rate limits (50 req/min for PAT)
- File exports may timeout for very large files
- Some features require team/organization plans
- Plugin API requires Figma desktop app running