Agent-Skills.md

Agent Skills: Figma API

Figma REST API for accessing design files, comments, components, and projects. Use this skill to read file contents, export images, manage comments, and integrate with Figma workspaces.

UncategorizedID: vm0-ai/vm0-skills/figma

Repository

vm0-ai/vm0-skills
vm0-ai
12

Skill Files

Browse the full folder contents for figma.

Download Skill

Loading file tree…

figma/SKILL.md

Skill Metadata

Name
figma
Description
Figma REST API for accessing design files, comments, components, and projects. Use this skill to read file contents, export images, manage comments, and integrate with Figma workspaces.

Figma API

Access and manage design files, components, comments, and projects in Figma workspaces via REST API.

Official docs: https://developers.figma.com/docs/rest-api/

When to Use

Use this skill when you need to:

  • Read design files and extract components, styles, and frames
  • Export images from Figma designs in various formats (PNG, JPG, SVG, PDF)
  • Get file version history and track changes
  • Manage comments on design files
  • List projects and files in a team
  • Access design tokens and styles
  • Get component information from design systems
  • Retrieve team and project metadata

Prerequisites

Getting Your API Token

  1. Log in to Figma
  2. Go to Settings page: https://www.figma.com/settings
  3. Scroll down to Personal access tokens section
  4. Click Generate new token
  5. Enter a token name (e.g., vm0-skills-test)
  6. Click Create and immediately copy the token (format: figd_...)
    • The token is only shown once - save it securely
    • If lost, you must delete and create a new token
export FIGMA_API_TOKEN="figd_..."

Verify Token

Test your token with this command:

bash -c 'curl -s -X GET "https://api.figma.com/v1/me" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"'

Expected response: Your user information (id, email, handle)

Finding File Keys

Figma file URLs contain the file key:

URL: https://www.figma.com/design/abc123XYZ/My-Design-File
File Key: abc123XYZ

The file key is the alphanumeric string between /design/ (or /file/) and the next /.

Rate Limits

  • 60 requests per minute per IP address
  • 429 status code = rate limited, retry after delay

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.[0]'

How to Use

All examples assume FIGMA_API_TOKEN is set.

Base URL: https://api.figma.com/v1

1. Get File

Retrieve complete file structure including frames, components, and styles. Replace <your-file-key> with your actual file key:

bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '{name, lastModified, version, document: .document.children[0].name}'

Get specific version:

bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>?version=123" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"'

2. Get File Nodes

Retrieve specific nodes from a file by node IDs. Replace <your-file-key> with your file key and <node-ids> with comma-separated node IDs (e.g., 1:2,1:3):

bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>/nodes?ids=<node-ids>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.nodes'

Node IDs can be found in the file structure or by appending ?node-id=X-Y to the Figma URL.

3. Get File Images

Export nodes as images in PNG, JPG, SVG, or PDF format. Replace <your-file-key> with your file key and <node-ids> with comma-separated node IDs:

bash -c 'curl -s -X GET "https://api.figma.com/v1/images/<your-file-key>?ids=<node-ids>&format=png&scale=2" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.images'

Parameters:

  • format: png, jpg, svg, pdf (default: png)
  • scale: 0.5, 1, 2, 4 (default: 1)
  • svg_outline_text: true to convert text to outlines in SVG
  • svg_include_id: true to include node IDs in SVG

Download an exported image. Replace <your-file-key> with your file key and <node-id> with the actual node ID:

IMAGE_URL="$(bash -c 'curl -s -X GET "https://api.figma.com/v1/images/<your-file-key>?ids=<node-id>&format=png" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq -r '.images["<node-id>"]')"

curl -s -o output.png "$IMAGE_URL"

4. Get Image Fills

Get download URLs for all images used in a file. Replace <your-file-key> with your file key:

bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>/images" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.meta.images'

5. Get File Comments

List all comments on a file. Replace <your-file-key> with your file key:

bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>/comments" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.comments[] | {id, message: .message, user: .user.handle, created_at}'

6. Post Comment

Add a comment to a file. Replace <your-file-key> with your file key.

Write to /tmp/figma_request.json:

{
  "message": "This looks great!",
  "client_meta": {"x": 100, "y": 200}
}

Then run:

bash -c 'curl -s -X POST "https://api.figma.com/v1/files/<your-file-key>/comments" -H "X-Figma-Token: ${FIGMA_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/figma_request.json'

To comment on a specific node, add client_meta with node coordinates.

7. Delete Comment

Delete a comment by ID. Replace <your-file-key> with your file key and <comment-id> with the comment ID:

curl -s -X DELETE "https://api.figma.com/v1/files/<your-file-key>/comments/<comment-id>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"

8. Get File Versions

List version history of a file. Replace <your-file-key> with your file key:

bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>/versions" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.versions[] | {id, created_at, label, description, user: .user.handle}'

9. Get Team Projects

List all projects in a team. Replace <your-team-id> with your team ID:

bash -c 'curl -s -X GET "https://api.figma.com/v1/teams/<your-team-id>/projects" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.projects[] | {id, name}'

To find your team ID, go to your Figma team page and extract it from the URL: https://www.figma.com/files/team/<your-team-id>/TeamName

10. Get Project Files

List all files in a project. Replace <your-project-id> with your project ID:

bash -c 'curl -s -X GET "https://api.figma.com/v1/projects/<your-project-id>/files" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.files[] | {key, name, last_modified}'

11. Get Team Components

Get all published components in a team. Replace <your-team-id> with your team ID:

bash -c 'curl -s -X GET "https://api.figma.com/v1/teams/<your-team-id>/components" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.meta.components[] | {key, name, description, containing_frame: .containing_frame.name}'

12. Get Component

Get metadata for a specific component. Replace <your-component-key> with your component key:

bash -c 'curl -s -X GET "https://api.figma.com/v1/components/<your-component-key>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '{key, name, description, containing_frame}'

13. Get Team Styles

Get all published styles (colors, text, effects, grids) in a team. Replace <your-team-id> with your team ID:

bash -c 'curl -s -X GET "https://api.figma.com/v1/teams/<your-team-id>/styles" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.meta.styles[] | {key, name, description, style_type}'

Style types: FILL, TEXT, EFFECT, GRID

14. Get Style

Get metadata for a specific style. Replace <your-style-key> with your style key:

bash -c 'curl -s -X GET "https://api.figma.com/v1/styles/<your-style-key>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '{key, name, description, style_type}'

15. Get Current User

Get information about the authenticated user:

bash -c 'curl -s -X GET "https://api.figma.com/v1/me" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '{id, email, handle, img_url}'

16. Get Team Members

List all members of a team. Replace <your-team-id> with your team ID:

bash -c 'curl -s -X GET "https://api.figma.com/v1/teams/<your-team-id>/members" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.members[] | {id, email: .user.email, handle: .user.handle, role}'

17. Get Component Sets

Get component sets (variants) in a file. Replace <your-file-key> with your file key:

bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>/component_sets" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.meta.component_sets[] | {key, name, description}'

18. Search Files

Search for files in a team (requires team ID). Replace <your-team-id> with your team ID and <search-query> with your search term:

bash -c 'curl -s -X GET "https://api.figma.com/v1/teams/<your-team-id>/files?name=<search-query>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.files[] | {key, name, last_modified}'

Common Workflows

Export All Frames as Images

Replace <your-file-key> with your file key. First, get all frame IDs:

bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq -r '.document.children[0].children[] | select(.type=="FRAME") | .id' | paste -sd "," -

Then export frames (replace <frame-ids> with the comma-separated frame IDs from the previous response):

bash -c 'curl -s -X GET "https://api.figma.com/v1/images/<your-file-key>?ids=<frame-ids>&format=png&scale=2" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.images'

Extract Design Tokens

Replace <your-file-key> with your file key:

# Get color styles
bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq '.styles | to_entries[] | select(.value.styleType == "FILL") | {name: .value.name, key: .value.key}'

Monitor File Changes

Replace <your-file-key> with your file key:

# Get current version
CURRENT_VERSION=$(bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"' | jq -r '.version')

echo "Current version: $CURRENT_VERSION"

Understanding File Structure

Figma files have a hierarchical structure:

FILE
└── CANVAS (page)
    ├── FRAME
    │   ├── RECTANGLE
    │   ├── TEXT
    │   └── GROUP
    │       └── VECTOR
    └── FRAME
        └── COMPONENT

Common node types: CANVAS, FRAME, GROUP, VECTOR, BOOLEAN_OPERATION, STAR, LINE, ELLIPSE, REGULAR_POLYGON, RECTANGLE, TEXT, SLICE, COMPONENT, COMPONENT_SET, INSTANCE

Guidelines

  1. Cache file data: File requests can be large; cache results when possible
  2. Use webhooks: For real-time updates, consider Figma webhooks instead of polling
  3. Respect rate limits: Implement exponential backoff for 429 responses
  4. Version control: Use version parameter to access specific file versions
  5. Optimize exports: Use appropriate scale and format for image exports to reduce file size
  6. Node IDs: Node IDs are in format X:Y (e.g., 1:2) and must be URL-encoded in some endpoints
  7. Team scope: Many operations require team-level access; ensure your token has team permissions
  8. Pagination: Some endpoints return paginated results; check for next_page in responses

API Reference

  • Main Documentation: https://developers.figma.com/docs/rest-api/
  • Authentication: https://developers.figma.com/docs/rest-api/authentication/
  • API Endpoints: https://developers.figma.com/docs/api/
  • Webhooks: https://developers.figma.com/docs/webhooks/
  • Plugins: https://www.figma.com/plugin-docs/
  • Token Settings: https://www.figma.com/settings (under Personal access tokens)