---
name: "Figma"
description: Read Figma files, frames, components, and comments, and export images through the Figma API.
version: 1
situations: figma, design, mockups, components, design review
requires-secrets: FIGMA_TOKEN
requires-packages:
requires-connector: figma
---

# Figma

Figma has no official CLI, so this skill uses its REST API with `curl` from your **bash** tool. The
personal access token reaches your shell as `$FIGMA_TOKEN` — never print it or write it anywhere.

```
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" https://api.figma.com/v1/me
```

That is the connection check. The API is read-mostly: you can read structure and write comments, but
you cannot edit a design through it.

## File keys

A Figma URL looks like `figma.com/design/<FILE_KEY>/<name>?node-id=1-234`. The file key is what the
API wants, and `node-id=1-234` becomes `1:234` in API calls — the dash is a URL artifact.

## Read

```
# Whole document tree — big; prefer depth-limited reads
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" "https://api.figma.com/v1/files/FILE_KEY?depth=2"

# Just some nodes
curl -s -H … "https://api.figma.com/v1/files/FILE_KEY/nodes?ids=1:234,1:567"

# Components and styles published from the file
curl -s -H … "https://api.figma.com/v1/files/FILE_KEY/components"

# Comments
curl -s -H … "https://api.figma.com/v1/files/FILE_KEY/comments"
```

A full file dump of a real design file is enormous. Start with `depth=1` or `depth=2`, find the page
or frame you want, then fetch that node by id.

## Export images

```
curl -s -H … "https://api.figma.com/v1/images/FILE_KEY?ids=1:234&format=png&scale=2"
```

That returns short-lived S3 URLs — download them right away with `curl -o` into the workspace if the
operator wants the files kept.

## Write

```
curl -s -X POST -H "X-Figma-Token: $FIGMA_TOKEN" -H "Content-Type: application/json" \
  https://api.figma.com/v1/files/FILE_KEY/comments \
  -d '{"message":"…","client_meta":{"node_id":"1:234","node_offset":{"x":0,"y":0}}}'
```

Comments are visible to the whole file's audience and they notify people. Show the text first.

## Never without being asked in this turn

Deleting comments, and posting comments on a file the operator did not name.