Figma Core Workflow A —— 设计令牌提取
概述
这是 Figma API 集成的主要工作流：从 Figma 文件中提取设计令牌（颜色、排版、间距），并将其转换为 CSS 自定义属性、JSON 令牌或 Tailwind 配置。
前提条件
- 已完成 figma-install-auth 设置
- 拥有带已发布样式或变量的 Figma 文件
- 已设置 FIGMA_PAT 和 FIGMA_FILE_KEY 环境变量
主要步骤
步骤 1：从文件获取样式 使用 FigmaClient 调用 GET /v1/files/:key，返回的 file.styles 是一个映射：nodeId -> { key, name, style_type, description }，其中 style_type 可为 "FILL" | "TEXT" | "EFFECT" | "GRID"。代码示例筛选出 colorStyles（FILL）和 textStyles（TEXT），并打印数量。
步骤 2：从节点解析样式值 获取实际节点以取得填充颜色和文本属性。调用 client.getFileNodes(fileKey, styleNodeIds)，遍历 nodesResponse.nodes。对颜色样式，检查 node.fills[0].type === 'SOLID'，将 Figma 的 0-1 浮点颜色转换为 0-255 的十六进制；若透明度 a < 1 则输出 rgba 格式，否则输出 hex。生成 DesignToken 对象数组，包含 name、type、value。
步骤 3：提取排版令牌 获取文本样式节点，检查 node.style，提取 fontFamily、fontSize（加 px）、fontWeight、lineHeight（lineHeightPx 加 px，否则 'normal'）、letterSpacing（加 px，否则 '0'），以 JSON 字符串形式存入 token 的 value。
步骤 4：生成 CSS 自定义属性 定义 tokensToCss 函数，将令牌名称转为小写并用连字符替换空格和斜杠，生成 :root { ... } 格式。颜色直接输出值；排版则展开为 -family、-size、-weight 等。使用 writeFileSync 写入 src/styles/tokens.css，并打印生成数量。
步骤 5：使用 Variables API（企业版） 调用 GET /v1/files/:key/variables/local（Tier 2，需要 file_variables:read 权限）。返回结构包含 vars.meta.variables 和 vars.meta.variableCollections。遍历变量，打印 collection.name/variable.name 和 resolvedType（"COLOR" | "FLOAT" | "STRING" | "BOOLEAN"），再遍历 valuesByMode，结合 collection.modes 找到 modeName 并打印各模式的值。
输出
- 从 Figma 样式或变量中提取的设计令牌
- 生成的 CSS 自定义属性文件
- 颜色值从 Figma 的 0-1 浮点格式转换为 hex/rgba
- 排版属性映射为 CSS 兼容值
错误处理
- 空样式映射：文件没有已发布样式，需先在 Figma 中发布样式
- 响应中节点为 null：节点已被删除，处理前过滤 null
- 变量端点返回 403：非企业版计划，改用样式端点
- 颜色看起来不对：忘记 0-1 到 0-255 的转换，转 hex 前乘以 255
示例
提取已发布样式的所有填充颜色并输出 CSS 自定义属性： 使用 curl 请求 https://api.figma.com/v1/files/${FIGMA_FILE_KEY}/styles，配合 jq 筛选 style_type 为 "FILL" 的节点，输出 node_id 和 name，例如 1:5 Color/Brand/Primary、1:6 Color/Brand/Secondary、1:9 Color/Neutral/100。然后将这些节点 ID 传给 /v1/files/:key/nodes?ids=...，运行步骤 4 的生成器，得到 :root { --color-brand-primary: #4f46e5; --color-brand-secondary: #22d3ee; --color-neutral-100: #f5f5f5; }。
完整令牌提取演练见 references/extract-typography-tokens.md 和 references/generate-css-custom-properties.md。
资源
- Figma File Endpoints
- Figma Variables API
- Design Tokens Format
下一步
如需导出资源，请参见 figma-core-workflow-b。
限制
Variables API 需要企业版计划。