UI 视觉设计 / 系统课时

选择 Figma 变量的导出方式

选择 Figma 变量的导出方式

同一套颜色、间距变量要交给前端使用时,导出方式决定了能否追溯来源、重复生成和识别变更。本篇以包含 Light、Dark 两个模式的设计库为例,选定可执行的导出路径,并建立每次交付的校验规则。

学习目标

  • 根据文件权限、更新频率和自动化要求,在插件、REST API 与受控手动导出间做选择。
  • 完成一次变量导出,并验证集合、模式和变量值是否齐全。
  • 用固定标识与历史快照区分新增、修改、删除,避免错误覆盖代码令牌。

用三个条件选择导出路径

先确认能否使用 Enterprise 变量 REST API,再看是否需要无人值守同步;不具备接口资格时,优先考虑文件内插件或 Figma 自带的模式导出。

路径 权限与运行位置 可重复性 差量同步能力
REST API Enterprise 资格、文件查看权限、file_variables:read;可在 CI 执行 高,脚本固定请求与转换版本 保存两次快照后可自动比较
插件 在有权访问的设计文件内运行;审查插件授权和外发数据范围 中到高,取决于插件版本与输出格式 通常需要自行保存快照并比对
受控手动导出 在 Figma 的 Variables 视图操作;无需编写脚本 中,依赖操作清单与人工复核 用版本控制的 JSON 文件比较

变量导出路径的选型决策流程

Figma 的变量 REST 接口目前限定 Enterprise 场景;读取至少需要文件查看权限和 file_variables:read,持有令牌并不意味着自动获得文件权限。以官方权限说明为准,先做一次真实请求再确定方案。

操作插件与受控手动导出

插件适合设计师主动交付,尤其是没有 REST 接口资格、却需要一次处理多个集合时。选用插件前,用测试文件分别建立 Colors 集合、Light/Dark 模式以及一个别名变量,检查导出是否保留集合、模式和别名引用。固定插件版本,避免更新后 JSON 结构悄然变化。

不使用插件时,可以采用 Figma 当前提供的模式 JSON 导出:

  1. 打开设计文件,在左侧导航进入 Variables 视图。
  2. 右键某个模式,选择 Export mode;如需导出集合的所有模式,右键集合选择 Export modes。
  3. 对每个需交付的集合执行导出,核对模式名、文件数和令牌值;将产物按 collection/mode 归档。
  4. 由另一人核对源文件与导出日期,并在代码仓库提交 JSON 差异。

模式导出采用设计令牌 JSON,不等于整份文件的完整变量关系快照;跨集合别名、隐藏项与元数据需要检查实际产物是否满足下游契约。菜单名称可对照官方模式导出说明。

使用 API 拉取可验证的快照

需要 CI 自动获取变量时,采用 GET /v1/files/:file_key/variables/local。它返回 meta.variables 与 meta.variableCollections,包含变量的 valuesByMode 和集合的 modes。同一响应还可能有本文件使用的远程变量,下游只处理目标范围内的 remote=false 项。

先在 Figma 账号设置的 Security → Personal access tokens 创建具有 file_variables:read 的令牌,取得设计文件 URL 中的 file key。在 Bash 环境预先设置 FIGMA_TOKEN、FIGMA_FILE_KEY,不要把密钥提交进仓库,然后运行:

bash
# 两个环境变量须事先赋值;令牌只用于读取源文件。
: "${FIGMA_TOKEN:?请先设置 FIGMA_TOKEN}"
: "${FIGMA_FILE_KEY:?请先设置 FIGMA_FILE_KEY}"
curl --fail --silent --show-error \
  -H "X-Figma-Token: ${FIGMA_TOKEN}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}/variables/local" \
  -o figma-variables.json

python3 - <<'PY'
import json
from pathlib import Path

# 校验实际接口结构,避免将异常响应入库。
data = json.loads(Path("figma-variables.json").read_text(encoding="utf-8"))
assert isinstance(data["meta"]["variables"], dict)
assert isinstance(data["meta"]["variableCollections"], dict)
print("variables payload OK")
PY

成功请求后的预期输出:

text
variables payload OK

生成的 figma-variables.json 才是原始快照;上述校验只确认字段类型,不能替代后续的语义校验。若使用 OAuth,应按 OAuth 方式传递 Bearer 令牌,而不是照搬个人令牌请求头。

用差量与发布门禁验收

以 color/action/primary 为例,假设本次将 Light 从 #2563EB 改为 #1D4ED8,Dark 仍是 #60A5FA。对比结果应是同一变量的 Light 值发生一次修改,而不是删除旧变量再新增变量。

对比对象 需要比较的字段 判定
变量 稳定 key 或源文件内 id、名称、类型、valuesByMode 新增/修改/删除
集合 集合标识、modes、defaultModeId 模式增删、重命名或默认值变化
别名 被引用变量标识及其所在模式 引用变更或目标丢失

保存上一版与本版原始快照,以稳定标识匹配;再转换成按名称组织的代码令牌。禁止仅凭变量名称判断身份,也不能把 Published API 的 subscribed_id 当作永久主键:它可能随修改发布而变化。/variables/published 虽有 updatedAt,却不包含模式值,不能单独用于完整令牌导出。

合入前执行三项检查:所有 Light/Dark 值齐全;别名目标存在且无循环;删除变量或模式时列出受影响组件并要求人工批准。这样一次导出才具备可追踪的版本边界。

排除权限与同步故障

请求返回 401,检查令牌是否有效;403 则核查 Enterprise 资格、账号席位、文件可见性与 file_variables:read,不要反复重试权限错误。429 表示限流,应读取响应头 Retry-After 后再重试,并避免每个变量单独发起请求。

若暂时无法开通接口,就回退到受审核的插件或模式导出,同时保持同一命名、模式清单与差量审查。导出路径可以不同,但进入代码仓库的令牌结构与验收门槛不应随工具变化。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

选择 Figma 变量的导出方式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通