figma-developer

Figma Developer

概述

使用 Figma REST API 自动化 Figma 到代码的桥接流程。提取设计令牌（颜色、字体排印、间距），并导出为 CSS 变量和 JSON；将图标导出为 SVG React 组件；根据 Figma 节点结构生成 React 组件；并设置 CI 流水线，实现持续同步设计。

适用场景： 将 Figma 中的设计令牌同步到代码、将图标集导出为 React 组件、根据 Figma 变体生成组件脚手架，以及在 CI 中设置自动化设计同步。

不适用场景： 手动进行一次性设计调整（直接复制数值即可）、开发 Figma 插件（改用 Plugin API）、实时协作编辑（直接使用 Figma webhooks），或没有 Figma 设计系统的项目。

快速参考

模式	API / 方法	要点
获取文件数据	GET /v1/files/:key	返回包含样式和填充的完整文档树
获取指定节点	GET /v1/files/:key/nodes?ids=...	仅获取所需节点，以减少负载
导出图像	GET /v1/images/:key?ids=...&format=svg	将节点渲染为 SVG/PNG/PDF；URL 会在 14 天后过期
获取样式	GET /v1/files/:key/styles	列出所有已发布的颜色、文本和效果样式
获取组件	GET /v1/files/:key/components	列出所有已发布的组件及其元数据
获取组件集	GET /v1/files/:key/component_sets	返回组件的变体分组
获取变量	GET /v1/files/:key/variables/local	提取 Figma Variables（颜色、间距等）
发布变量	POST /v1/variables	在整个组织中发布本地变量
提取令牌	解析文件响应中的样式，并转换为 CSS/JSON	不存在内置的“提取令牌”端点
CI 同步	GitHub Actions cron + peter-evans/create-pull-request	Figma 文件更改时自动创建 PR

Figma 文件组织

区域	内容
颜色	所有颜色样式，使用 / 层级结构（Primary/500）
字体排印	文本样式（Heading/Large、Body/Regular）
间距	间距指南中的数值
组件	变体分组（Button/Primary、Card/Default）
图标	所有图标都放在一个可导出的画框中

常见错误

错误	修正
使用虚构的 API 方法，如 extractDesignTokens()	手动解析 GET /v1/files/:key 响应中的样式
硬编码 Figma 值，而不使用令牌	将令牌提取为 CSS 变量，并通过 var() 引用
未规范化 Figma 样式名称	转为小写，并将特殊字符替换为连字符
忘记 Figma 使用 0-1 RGB，而非 0-255	乘以 255 并四舍五入，然后再转换为十六进制
未缓存 API 响应	使用 TTL 缓存，避免触发速率限制
手动导出图标	使用 GET /v1/images/:key 和 React 组件生成来实现自动化
没有 CI 同步工作流	使用 GitHub Actions cron 和 create-pull-request action
使用过期的图片 URL	图片导出 URL 会在 14 天后过期；使用前重新获取

库

软件包	用途
figma-api	社区开发的 Figma REST API 客户端（带类型）
@figma/rest-api-spec	Figma API 的官方 TypeScript 类型定义
style-dictionary	在不同平台间转换设计令牌
svgo	使用前优化导出的 SVG
@svgr/core	将 SVG 文件转换为 React 组件

委派

• 设计系统：请参阅 design-system 技能
• 资源优化：请参阅 asset-manager 技能

参考资料

• 设置与身份验证
• 设计令牌
• 资源导出
• 组件生成
• CI 自动化
• 故障排除