figma

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Figma API

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/

通过REST API访问和管理Figma工作区中的设计文件、组件、评论和项目。
官方文档:
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

在以下场景中使用该技能:
  • 读取设计文件并提取组件、样式和框架
  • 导出图片:将Figma设计导出为多种格式(PNG、JPG、SVG、PDF)
  • 获取文件版本历史并追踪变更
  • 管理设计文件的评论
  • 列出团队中的项目和文件
  • 访问设计令牌和样式
  • 从设计系统中获取组件信息
  • 检索团队和项目元数据

Prerequisites

前提条件

Getting Your API Token

获取API令牌

  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
bash
export FIGMA_API_TOKEN="figd_..."
  1. 登录Figma
  2. 进入设置页面:https://www.figma.com/settings
  3. 滚动到个人访问令牌部分
  4. 点击生成新令牌
  5. 输入令牌名称(例如:
    vm0-skills-test
  6. 点击创建立即复制令牌(格式:
    figd_...
    • 令牌仅显示一次,请妥善保存
    • 若丢失,必须删除并重新创建新令牌
bash
export FIGMA_API_TOKEN="figd_..."

Verify Token

验证令牌

Test your token with this command:
bash
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)
使用以下命令测试令牌:
bash
bash -c 'curl -s -X GET "https://api.figma.com/v1/me" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"'
预期响应:你的用户信息(ID、邮箱、用户名)

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
/
.
Figma文件URL中包含文件密钥:
URL: https://www.figma.com/design/abc123XYZ/My-Design-File
文件密钥: abc123XYZ
文件密钥是
/design/
(或
/file/
)与下一个
/
之间的字母数字字符串。

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
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.[0]'
  • 每个IP地址每分钟最多60次请求
  • 收到429状态码表示超出速率限制,请延迟后重试

重要提示: 当在包含管道的命令中使用
$VAR
时,请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的bug,直接使用管道时环境变量会被静默清除。
bash
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

所有示例均假设已设置
FIGMA_API_TOKEN
基础URL:
https://api.figma.com/v1

1. Get File

1. 获取文件

Retrieve complete file structure including frames, components, and styles. Replace
<your-file-key>
with your actual file key:
bash
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
bash -c 'curl -s -X GET "https://api.figma.com/v1/files/<your-file-key>?version=123" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"'

检索包含框架、组件和样式的完整文件结构。将
<your-file-key>
替换为实际的文件密钥:
bash
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}'
获取特定版本:
bash
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

2. 获取文件节点

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
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.

通过节点ID检索文件中的特定节点。将
<your-file-key>
替换为文件密钥,
<node-ids>
替换为逗号分隔的节点ID(例如:
1:2,1:3
):
bash
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'
节点ID可在文件结构中找到,或通过在Figma URL后追加
?node-id=X-Y
获取。

3. Get File Images

3. 获取文件图片

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
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:
bash
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"

将节点导出为PNG、JPG、SVG或PDF格式的图片。将
<your-file-key>
替换为文件密钥,
<node-ids>
替换为逗号分隔的节点ID:
bash
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'
参数说明:
  • format
    png
    jpg
    svg
    pdf
    (默认值:
    png
  • scale
    0.5
    1
    2
    4
    (默认值:
    1
  • svg_outline_text
    :设为
    true
    可将SVG中的文本转换为轮廓
  • svg_include_id
    :设为
    true
    可在SVG中包含节点ID
下载导出的图片。将
<your-file-key>
替换为文件密钥,
<node-id>
替换为实际的节点ID:
bash
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

4. 获取图片填充

Get download URLs for all images used in a file. Replace
<your-file-key>
with your file key:
bash
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'

获取文件中所有使用图片的下载链接。将
<your-file-key>
替换为文件密钥:
bash
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

5. 获取文件评论

List all comments on a file. Replace
<your-file-key>
with your file key:
bash
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}'

列出文件中的所有评论。将
<your-file-key>
替换为文件密钥:
bash
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

6. 添加评论

Add a comment to a file. Replace
<your-file-key>
with your file key.
Write to
/tmp/figma_request.json
:
json
{
  "message": "This looks great!",
  "client_meta": {"x": 100, "y": 200}
}
Then run:
bash
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.

为文件添加评论。将
<your-file-key>
替换为文件密钥。
写入
/tmp/figma_request.json
json
{
  "message": "This looks great!",
  "client_meta": {"x": 100, "y": 200}
}
然后运行:
bash
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'
若要对特定节点评论,请添加包含节点坐标的
client_meta

7. Delete Comment

7. 删除评论

Delete a comment by ID. Replace
<your-file-key>
with your file key and
<comment-id>
with the comment ID:
bash
curl -s -X DELETE "https://api.figma.com/v1/files/<your-file-key>/comments/<comment-id>" -H "X-Figma-Token: ${FIGMA_API_TOKEN}"

通过ID删除评论。将
<your-file-key>
替换为文件密钥,
<comment-id>
替换为评论ID:
bash
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

8. 获取文件版本

List version history of a file. Replace
<your-file-key>
with your file key:
bash
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}'

列出文件的版本历史。将
<your-file-key>
替换为文件密钥:
bash
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

9. 获取团队项目

List all projects in a team. Replace
<your-team-id>
with your team ID:
bash
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

列出团队中的所有项目。将
<your-team-id>
替换为团队ID:
bash
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}'
查找团队ID:进入Figma团队页面,从URL中提取:
https://www.figma.com/files/team/<your-team-id>/TeamName

10. Get Project Files

10. 获取项目文件

List all files in a project. Replace
<your-project-id>
with your project ID:
bash
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}'

列出项目中的所有文件。将
<your-project-id>
替换为项目ID:
bash
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

11. 获取团队组件

Get all published components in a team. Replace
<your-team-id>
with your team ID:
bash
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}'

获取团队中所有已发布的组件。将
<your-team-id>
替换为团队ID:
bash
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

12. 获取组件

Get metadata for a specific component. Replace
<your-component-key>
with your component key:
bash
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}'

获取特定组件的元数据。将
<your-component-key>
替换为组件密钥:
bash
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

13. 获取团队样式

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

获取团队中所有已发布的样式(颜色、文本、效果、网格)。将
<your-team-id>
替换为团队ID:
bash
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}'
样式类型:
FILL
TEXT
EFFECT
GRID

14. Get Style

14. 获取样式

Get metadata for a specific style. Replace
<your-style-key>
with your style key:
bash
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}'

获取特定样式的元数据。将
<your-style-key>
替换为样式密钥:
bash
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

15. 获取当前用户

Get information about the authenticated user:
bash
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}'

获取已认证用户的信息:
bash
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

16. 获取团队成员

List all members of a team. Replace
<your-team-id>
with your team ID:
bash
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}'

列出团队中的所有成员。将
<your-team-id>
替换为团队ID:
bash
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

17. 获取组件集

Get component sets (variants) in a file. Replace
<your-file-key>
with your file key:
bash
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}'

获取文件中的组件集(变体)。将
<your-file-key>
替换为文件密钥:
bash
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

18. 搜索文件

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
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}'

在团队中搜索文件(需要团队ID)。将
<your-team-id>
替换为团队ID,
<search-query>
替换为搜索关键词:
bash
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
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
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'
<your-file-key>
替换为文件密钥。首先,获取所有框架ID:
bash
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 "," -
然后导出框架(将
<frame-ids>
替换为上一步响应中逗号分隔的框架ID):
bash
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:
bash
undefined
<your-file-key>
替换为文件密钥:
bash
undefined

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}'
undefined
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}'
undefined

Monitor File Changes

监控文件变更

Replace
<your-file-key>
with your file key:
bash
undefined
<your-file-key>
替换为文件密钥:
bash
undefined

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"

---
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

Figma文件采用层级结构:
文件
└── 画布(页面)
    ├── 框架
    │   ├── 矩形
    │   ├── 文本
    │   └── 组
    │       └── 矢量
    └── 框架
        └── 组件
常见节点类型:
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

  1. 缓存文件数据:文件请求可能较大,尽可能缓存结果
  2. 使用Webhooks:如需实时更新,考虑使用Figma Webhooks而非轮询
  3. 遵守速率限制:针对429响应实现指数退避机制
  4. 版本控制:使用
    version
    参数访问特定文件版本
  5. 优化导出:为图片导出选择合适的比例和格式以减小文件大小
  6. 节点ID:节点ID格式为
    X:Y
    (例如:
    1:2
    ),在某些端点中必须进行URL编码
  7. 团队权限:许多操作需要团队级访问权限,请确保你的令牌拥有团队权限
  8. 分页处理:部分端点返回分页结果,请检查响应中的
    next_page

API Reference

API参考