figma
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFigma 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令牌
- Log in to Figma
- Go to Settings page: https://www.figma.com/settings
- Scroll down to Personal access tokens section
- Click Generate new token
- Enter a token name (e.g., )
vm0-skills-test - 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_..."- 登录Figma
- 进入设置页面:https://www.figma.com/settings
- 滚动到个人访问令牌部分
- 点击生成新令牌
- 输入令牌名称(例如:)
vm0-skills-test - 点击创建并立即复制令牌(格式:)
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: abc123XYZThe file key is the alphanumeric string between (or ) and the next .
/design//file//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 usingin a command that pipes to another command, wrap the command containing$VARin$VAR. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.bash -c '...'bashbash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.[0]'
- 每个IP地址每分钟最多60次请求
- 收到429状态码表示超出速率限制,请延迟后重试
重要提示: 当在包含管道的命令中使用时,请将包含$VAR的命令用$VAR包裹。由于Claude Code的bug,直接使用管道时环境变量会被静默清除。bash -c '...'bashbash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.[0]'
How to Use
使用方法
All examples assume is set.
FIGMA_API_TOKENBase URL:
https://api.figma.com/v1所有示例均假设已设置。
FIGMA_API_TOKEN基础URL:
https://api.figma.com/v11. Get File
1. 获取文件
Retrieve complete file structure including frames, components, and styles. Replace with your actual file key:
<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}'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 with your file key and with comma-separated node IDs (e.g., ):
<your-file-key><node-ids>1:2,1:3bash
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 to the Figma URL.
?node-id=X-Y通过节点ID检索文件中的特定节点。将替换为文件密钥,替换为逗号分隔的节点ID(例如:):
<your-file-key><node-ids>1:2,1:3bash
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-Y3. Get File Images
3. 获取文件图片
Export nodes as images in PNG, JPG, SVG, or PDF format. Replace with your file key and with comma-separated node IDs:
<your-file-key><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(default:pdf)png - :
scale,0.5,1,2(default:4)1 - :
svg_outline_textto convert text to outlines in SVGtrue - :
svg_include_idto include node IDs in SVGtrue
Download an exported image. Replace with your file key and with the actual node ID:
<your-file-key><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格式的图片。将替换为文件密钥,替换为逗号分隔的节点ID:
<your-file-key><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'参数说明:
- :
format、png、jpg、svg(默认值:pdf)png - :
scale、0.5、1、2(默认值:4)1 - :设为
svg_outline_text可将SVG中的文本转换为轮廓true - :设为
svg_include_id可在SVG中包含节点IDtrue
下载导出的图片。将替换为文件密钥,替换为实际的节点ID:
<your-file-key><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"4. Get Image Fills
4. 获取图片填充
Get download URLs for all images used in a file. Replace with your file key:
<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 with your file key:
<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 with your file key.
<your-file-key>Write to :
/tmp/figma_request.jsonjson
{
"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 with node coordinates.
client_meta为文件添加评论。将替换为文件密钥。
<your-file-key>写入:
/tmp/figma_request.jsonjson
{
"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_meta7. Delete Comment
7. 删除评论
Delete a comment by ID. Replace with your file key and with the comment ID:
<your-file-key><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删除评论。将替换为文件密钥,替换为评论ID:
<your-file-key><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}"8. Get File Versions
8. 获取文件版本
List version history of a file. Replace with your file key:
<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 with your team ID:
<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列出团队中的所有项目。将替换为团队ID:
<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}'查找团队ID:进入Figma团队页面,从URL中提取:
https://www.figma.com/files/team/<your-team-id>/TeamName10. Get Project Files
10. 获取项目文件
List all files in a project. Replace with your project ID:
<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}'列出项目中的所有文件。将替换为项目ID:
<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}'11. Get Team Components
11. 获取团队组件
Get all published components in a team. Replace with your team ID:
<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}'获取团队中所有已发布的组件。将替换为团队ID:
<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}'12. Get Component
12. 获取组件
Get metadata for a specific component. Replace with your component key:
<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 with your team ID:
<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: , , ,
FILLTEXTEFFECTGRID获取团队中所有已发布的样式(颜色、文本、效果、网格)。将替换为团队ID:
<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}'样式类型: 、、、
FILLTEXTEFFECTGRID14. Get Style
14. 获取样式
Get metadata for a specific style. Replace with your style key:
<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 with your team ID:
<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}'列出团队中的所有成员。将替换为团队ID:
<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}'17. Get Component Sets
17. 获取组件集
Get component sets (variants) in a file. Replace with your file key:
<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 with your team ID and with your search term:
<your-team-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}'在团队中搜索文件(需要团队ID)。将替换为团队ID,替换为搜索关键词:
<your-team-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 with your file key. First, get all frame IDs:
<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 -r '.document.children[0].children[] | select(.type=="FRAME") | .id' | paste -sd "," -Then export frames (replace with the comma-separated frame IDs from the previous response):
<frame-ids>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'将替换为文件密钥。首先,获取所有框架ID:
<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 -r '.document.children[0].children[] | select(.type=="FRAME") | .id' | paste -sd "," -然后导出框架(将替换为上一步响应中逗号分隔的框架ID):
<frame-ids>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 with your file key:
<your-file-key>bash
undefined将替换为文件密钥:
<your-file-key>bash
undefinedGet 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}'
undefinedbash -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}'
undefinedMonitor File Changes
监控文件变更
Replace with your file key:
<your-file-key>bash
undefined将替换为文件密钥:
<your-file-key>bash
undefinedGet 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
└── COMPONENTCommon node types: , , , , , , , , , , , , , ,
CANVASFRAMEGROUPVECTORBOOLEAN_OPERATIONSTARLINEELLIPSEREGULAR_POLYGONRECTANGLETEXTSLICECOMPONENTCOMPONENT_SETINSTANCEFigma文件采用层级结构:
文件
└── 画布(页面)
├── 框架
│ ├── 矩形
│ ├── 文本
│ └── 组
│ └── 矢量
└── 框架
└── 组件常见节点类型:、、、、、、、、、、、、、、
CANVASFRAMEGROUPVECTORBOOLEAN_OPERATIONSTARLINEELLIPSEREGULAR_POLYGONRECTANGLETEXTSLICECOMPONENTCOMPONENT_SETINSTANCEGuidelines
注意事项
- Cache file data: File requests can be large; cache results when possible
- Use webhooks: For real-time updates, consider Figma webhooks instead of polling
- Respect rate limits: Implement exponential backoff for 429 responses
- Version control: Use parameter to access specific file versions
version - Optimize exports: Use appropriate scale and format for image exports to reduce file size
- Node IDs: Node IDs are in format (e.g.,
X:Y) and must be URL-encoded in some endpoints1:2 - Team scope: Many operations require team-level access; ensure your token has team permissions
- Pagination: Some endpoints return paginated results; check for in responses
next_page
- 缓存文件数据:文件请求可能较大,尽可能缓存结果
- 使用Webhooks:如需实时更新,考虑使用Figma Webhooks而非轮询
- 遵守速率限制:针对429响应实现指数退避机制
- 版本控制:使用参数访问特定文件版本
version - 优化导出:为图片导出选择合适的比例和格式以减小文件大小
- 节点ID:节点ID格式为(例如:
X:Y),在某些端点中必须进行URL编码1:2 - 团队权限:许多操作需要团队级访问权限,请确保你的令牌拥有团队权限
- 分页处理:部分端点返回分页结果,请检查响应中的
next_page
API Reference
API参考
- 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)