UI 视觉设计 / 系统课时
导入 DTCG JSON 并核对映射
导入 DTCG JSON 并核对映射
这次把一份 DTCG Token 文件导入 Figma Design,建立可在画布中引用的变量,再检查名称、类型、模式和别名是否正确。最终得到一张逐项核对表,并能区分格式错误、类型不支持和更新未命中三类问题。
学习目标
- 按 Figma 原生入口新建变量集合,或将 JSON 导入已有模式。
- 识别 DTCG Token 到 Figma 变量的名称、类型与别名映射。
- 根据导入后的变量数量和实际取值定位遗漏项。
准备符合导入规则的 JSON
在有编辑权限的 Figma Design 文件中操作。将下面内容保存为 UTF-8 文件 light.tokens.json。这是完整的 DTCG 文件,不是 Figma 插件专用格式;每个 Token 使用 $type 和 $value 描述类型与值。
{
"palette": {
"brand": {
"600": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0.145098, 0.388235, 0.921569],
"alpha": 1,
"hex": "#2563EB"
}
}
}
},
"semantic": {
"action": {
"primary": {
"$type": "color",
"$value": "{palette.brand.600}"
}
}
},
"space": {
"md": {
"$type": "dimension",
"$value": {"value": 16, "unit": "px"}
}
},
"motion": {
"fast": {
"$type": "duration",
"$value": {"value": 0.2, "unit": "s"}
}
},
"font": {
"ui": {
"$type": "fontFamily",
"$value": "Inter"
}
},
"feature": {
"visible": {
"$type": "number",
"$value": 1,
"$extensions": {"com.figma.type": "boolean"}
}
}
}预期结果:文件包含 6 个 Token,其中 semantic.action.primary 引用 palette.brand.600,并非复制一份蓝色色值。颜色对象同时给出 sRGB 分量和对应的十六进制色值;space.md 使用 px,motion.fast 使用 s,以满足原生导入的单位限制。
在变量视图中新建与更新模式
以下操作适用于支持原生 DTCG 模式导入的 Figma Design 界面;模式数量受账户方案限制。若要建立 Light、Dark 双模式,应准备两份同名、同类型、完整字段的 JSON,不能只在 Dark 文件保留改动项。
- 在设计文件左侧导航选择 Variables,进入变量视图。
- 从集合侧栏的 More options → Create collection 创建集合,命名为
Design Tokens。 - 把
light.tokens.json拖进变量视图。新建导入时,每个 JSON 文件对应一个模式;若同时新建 Light、Dark 两列,需一次拖入两份文件,并核对导入后的模式列名称。 - 若已有目标模式,右键单击它的列标题,选择 Import mode,再选择 JSON 文件。此操作只更新名称和类型都匹配的现有变量,不等于重新创建整个集合。

不要把“拖入新集合”和“导入已有模式”混用:前者用于建立变量及模式,后者适合回写既有模式的数值。先在测试文件确认映射,再对正式共享变量集合操作,以免覆盖已有人为修订。
对照名称、类型和别名
导入后打开 Design Tokens 集合,逐行比对下表。嵌套组路径会被 Figma 归一为斜杠分隔的变量名,且 dimension、duration 最终都落在 Number 类型,不保留独立的长度或时间变量类型。
| DTCG 路径 | Figma 变量 | 预期类型和值 |
|---|---|---|
palette.brand.600 |
palette/brand/600 |
Color,#2563EB |
semantic.action.primary |
semantic/action/primary |
Color,指向品牌蓝变量的别名 |
space.md |
space/md |
Number,16 |
motion.fast |
motion/fast |
Number,0.2 |
font.ui |
font/ui |
String,Inter |
feature.visible |
feature/visible |
Boolean,true |
尤其要检查归一化冲突:若同一文件同时存在顶层键 color.accent.light 和嵌套路径 color → accent → light,两者最终都可能变为 color/accent/light。Figma 只导入先遇到的一项,因此应在源文件中统一命名,不要依赖导入顺序覆盖。
排查未导入的 Token
Figma 原生导入支持的范围比完整 DTCG 规范窄。逐项核对失败项目,优先从原始 JSON 修正,而不是在 Figma 中补一个同名但失去源文件关联的变量。
- 颜色仅支持 sRGB、HSL;
oklch等色彩空间需在源端明确转换并检查色差。 dimension只接受px,duration只接受s;rem、ms不能直接照搬导入。fontFamily必须是单个字体名称字符串;包含回退字体的数组不受支持。shadow、typography等复合 Token 不能按一个原生变量完整导入。应保留在代码构建链或另行设计 Figma 样式的映射,不要声称已同步。
跨集合别名还需目标变量已存在且可访问,并借助 Figma 的 com.figma.aliasData 扩展提供目标集合和变量信息;普通 {path} 引用不能保证自动找到另一集合的对象。
验收一次导入与回写
先在变量视图确认 6 行变量,并找到与导入文件对应的模式列,分别查看 16、0.2、true 和别名目标。然后新建一个矩形,把填充绑定到 semantic/action/primary:画布应显示品牌蓝色,变量编辑器里应显示别名引用关系,而不只是相同色值。
验证更新时,先备份源文件,将 light.tokens.json 中品牌蓝的 hex 改为 #60A5FA、components 改为 [0.376471, 0.647059, 0.980392],再在 light.tokens.json 对应的模式列执行 Import mode。预期相同名称与类型的变量值被更新,绑定该变量的矩形随之换色;变量未出现或未变化时,优先检查文件路径、名称归一化、类型是否变化及导入模式是否选错。
Figma 的官方变量模式与导入说明可用于复核支持列表。验收记录至少保存“源 Token 路径、Figma 变量名、类型、当前模式值、别名目标、是否一致”六列,之后回写时才能准确发现变化。