Figma Connector

SKILL.md

---
name: figma-connector
description: "Access Figma design files with managed OAuth. Browse files, read file metadata, get comments, and view project contents. Use when the user wants to list Figma files, read design file metadata, view comments on a file, list projects, or access Figma design data."
metadata:
  polly:
    polly_managed_connector: true
    auth:
      - env: FIGMA_ACCESS_TOKEN
        type: oauth2
        integration_id: figma
        description: Figma OAuth access
        scopes:
          - file_content:read
          - file_metadata:read
          - projects:read
          - file_comments:read
          - file_comments:write
          - current_user:read
    primaryEnv: FIGMA_ACCESS_TOKEN
---

# Figma Connector

Access Figma through the Figma REST API using managed OAuth.

## First-Time Setup

If Figma is not connected yet, run:

`manage_auth(action="connect", integration_id="figma", auth_env="FIGMA_ACCESS_TOKEN")`

## Auth & Security

- Authentication is managed by Polly + Nango from `metadata.polly.auth`
- Never ask users to paste tokens in chat
- Never print or log token values
- If auth fails, reconnect with:
  `manage_auth(action="connect", integration_id="figma", auth_env="FIGMA_ACCESS_TOKEN")`

## Base URL

`https://api.figma.com/v1`

All requests include:

`Authorization: Bearer $FIGMA_ACCESS_TOKEN`

## ID Extraction

Always extract IDs from URLs rather than asking the user for raw IDs.

**Team ID** — extract from team page URLs:
- `figma.com/files/team/1554537187006092161/...` → team ID: `1554537187006092161`

**File Key** — extract from file URLs:
- `figma.com/file/0LCpKYJ4e8dnwwQXDjAoW2/FileName` → file key: `0LCpKYJ4e8dnwwQXDjAoW2`
- `figma.com/design/0LCpKYJ4e8dnwwQXDjAoW2/FileName` → file key: `0LCpKYJ4e8dnwwQXDjAoW2`

```python
import re

def extract_team_id(url):
    m = re.search(r'/team/(\d+)', url)
    return m.group(1) if m else None

def extract_file_key(url):
    m = re.search(r'/(?:file|design)/([A-Za-z0-9]+)', url)
    return m.group(1) if m else None
```

## Team ID Handling

Many operations require a team ID. Resolution order:

1. Extract from a URL the user provides
2. Check memory for a previously saved team ID
3. Ask: *"What's your Figma team URL?"* and extract the ID

After resolving, save to memory:
`update_memory(operation="set", key="figma_team_id", value="<team_id>")`

## Common Operations

**Get current user:**
```bash
curl -sS -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/me"
```

**List team projects** (requires team ID):
```bash
curl -sS -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/teams/<teamId>/projects"
```

**List project files:**
```bash
curl -sS -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/projects/<projectId>/files"
```

**Get file metadata (shallow):**
```bash
curl -sS -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/files/<fileKey>?depth=1"
```

**Get comments on a file:**
```bash
curl -sS -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/files/<fileKey>/comments"
```

**Post a comment:**
```bash
curl -sS -X POST \
  -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Comment text"}' \
  "https://api.figma.com/v1/files/<fileKey>/comments"
```

**Get file versions:**
```bash
curl -sS -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/files/<fileKey>/versions"
```

**Export node as image:**
```bash
curl -sS -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/images/<fileKey>?ids=<nodeId>&format=png&scale=1"
```

**Get team components:**
```bash
curl -sS -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/teams/<teamId>/components"
```

**Get team styles:**
```bash
curl -sS -H "Authorization: Bearer $FIGMA_ACCESS_TOKEN" \
  "https://api.figma.com/v1/teams/<teamId>/styles"
```

## Scope Limitations

| Capability | Status |
|---|---|
| Files, projects, comments, versions, images | ✅ Available |
| Team components, styles, component sets | ✅ Available |
| Variables (`/variables/local`) | ❌ Requires `file_variables:read` scope + Enterprise/Professional plan |

## Rules

- Use `depth=1` when only metadata is needed to reduce response size
- Always extract team/file IDs from URLs — never ask users for raw IDs
- Save team ID to memory after first resolution
- On 401/403, reconnect via `manage_auth`
- Never log, echo, or expose credential values in any output