# Figma API Reference

## Authentication

Get your Figma access token from: https://www.figma.com/developers/api#access-tokens

Set it in `.env`:
```
FIGMA_ACCESS_TOKEN=your_token_here
```

## File Structure

Figma files have a hierarchical structure:

```
Document
└── Canvas (Page)
    └── Frame
        └── Group/Component/Text/Rectangle/etc.
```

## Key Endpoints

### Get File
```
GET /v1/files/:file_key
```

Returns the full file structure including:
- All pages (canvases)
- All frames and nested nodes
- Styles, colors, typography
- Components and instances

### Get File Nodes
```
GET /v1/files/:file_key/nodes?ids=node_id1,node_id2
```

Get specific nodes by ID.

### Get Images
```
GET /v1/images/:file_key?ids=node_id1,node_id2&format=png&scale=2
```

Export nodes as images.

## Node Types

- `DOCUMENT` - Root
- `CANVAS` - Page
- `FRAME` - Container frame
- `GROUP` - Group
- `COMPONENT` - Component definition
- `INSTANCE` - Component instance
- `TEXT` - Text layer
- `RECTANGLE`, `ELLIPSE`, `POLYGON`, `STAR`, `LINE`, `VECTOR` - Shapes
- `BOOLEAN_OPERATION` - Boolean shapes

## Color Format

Colors in Figma API use RGBA with values 0-1:

```json
{
  "r": 1,
  "g": 0.42,
  "b": 0.21,
  "a": 1
}
```

Convert to hex:
```javascript
const hex = `#${Math.round(r*255).toString(16)}${Math.round(g*255).toString(16)}${Math.round(b*255).toString(16)}`;
```

## Typography Properties

Text nodes have a `style` object:

```json
{
  "fontFamily": "Inter",
  "fontWeight": 600,
  "fontSize": 16,
  "letterSpacing": 0,
  "lineHeightPx": 24
}
```

## Layout Properties

Auto-layout frames have spacing properties:

```json
{
  "paddingLeft": 16,
  "paddingRight": 16,
  "paddingTop": 12,
  "paddingBottom": 12,
  "itemSpacing": 8,
  "layoutMode": "HORIZONTAL"
}
```

## Corner Radius

```json
{
  "cornerRadius": 8,
  "rectangleCornerRadii": [8, 8, 8, 8]
}
```

## Rate Limits

- 30 requests per minute per token
- Burst of 10 requests
- Use caching when possible

## Best Practices

1. **Cache file data** - Files don't change that often
2. **Batch node requests** - Get multiple nodes in one call
3. **Use node IDs** - More efficient than traversing the tree
4. **Filter early** - Skip non-relevant nodes ASAP
5. **Respect rate limits** - Add delays between bulk operations