UI 视觉设计 / 系统课时
处理工具类型与数据同步差异
处理工具类型与数据同步差异
把 DTCG Token 同步到 Figma 后,组件颜色看似正确,引用关系却可能已经断开;反向导出还会丢失单位、主题映射或样式结构。本篇建立类型映射、差异分类和可运行的审计脚本,让设计数据与工程源文件能够逐项核对。
学习目标
- 区分 Figma 变量、样式与 DTCG Token 的表达边界。
- 识别类型不兼容、别名丢失、名称冲突与 Mode 映射偏差。
- 运行差异审计,并按明确的阻断条件验收同步结果。
比较变量、样式与 Token 的能力
Figma 变量的 resolvedType 为 COLOR、FLOAT、STRING 或 BOOLEAN,同一 Collection 可按 Mode 保存不同值。样式适合承载文字排版、渐变和多层效果;样式可以绑定变量,但不能像变量一样被其他变量引用。
| 表达对象 | 擅长保存 | 不能直接等同的内容 |
|---|---|---|
| Figma Variable | 单值、Mode、变量别名 | 完整的排版或多层阴影复合对象 |
| Figma Style | Text、Paint、Effect 等属性组合 | 变量的多 Mode 值与别名身份 |
| DTCG Token | $type、$value、别名、复合类型 |
Figma 的 Collection、Mode 和 Style 节点 |
DTCG 2025.10 用独立 Resolver 的上下文组合表达主题,不能把 Figma 的 valuesByMode 原样塞进某个 $value。另外,DTCG color 的值是包含 colorSpace 与 components 的颜色对象,不是直接以十六进制字符串充当 $value。核对时可参照 DTCG 格式规范 与 Figma 变量类型。
建立可追溯的转换映射
约定 Git 内的 .tokens.json 和 .resolver.json 是经过审核的权威源。转换器向 Figma 写入能表达的变量与样式;反向抽取只生成差异清单,不自动覆盖源文件。转换前给每条记录保存 tokenPath、Figma variable.key 或样式标识、Collection、Mode、类型、引用目标和单位。

| DTCG 表达 | Figma 落点 | 必须保留的额外信息 |
|---|---|---|
color(含色域、透明度) |
COLOR 变量 |
原始色域、alpha、转换精度 |
dimension:16px |
FLOAT:16 |
unit=px;不能反向猜成 rem |
fontFamily、number |
适用时用 STRING、FLOAT |
字体回退列表、具体用途 |
typography、shadow、gradient |
文字、效果或绘制样式 | 子属性绑定、层次顺序及无法表示的字段 |
例如 space.card.padding 在 DTCG 中应是 $type: dimension,$value 含 value: 16 和 unit: px;映射到 Figma 的 FLOAT=16 后,必须从映射清单找回单位。Figma 的普通布尔值或任意文本也不能随意声明为 DTCG 标准的 boolean、string 类型:没有合适的标准类型时应记录不兼容,或在约定的扩展元数据中保留。
识别四种需要阻断的差异
- 类型不兼容:目标应为
FLOAT的间距变量被建成STRING。不要把字符串16直接写回尺寸 Token;先修复变量类型,再用单位映射恢复16px。 - 别名丢失:
color.action.primary应引用{color.brand.600},但 Figma 只剩解析后的#2359C4。Figma REST 数据里的别名由VARIABLE_ALIAS和目标id表示;抽取时必须把目标 ID 还原为 Token 路径,不能仅比较最终色值。 - 名称冲突:
Color/Brand/600与color/brand/600在统一小写、斜杠转点号后都成为color.brand.600。DTCG 名称本身区分大小写,但发布到代码平台后可能冲突;应报错并人工改名,不应让后者静默覆盖前者。 - 主题错位:Figma 的
Light、Dark是各自的 Mode ID;应显式映射到 Resolver 的theme=light/dark,分别核对每一模式,不能只比较默认模式。
运行最小差异审计脚本
下例使用 Python 3 标准库。source 是已把 DTCG 类型转换成 Figma 目标类型的审计快照;figma 是从 API 或插件结果整理后的模拟快照,并非原始 REST 响应。实际接入时,还需按 variable.key 建立身份表,并把 valuesByMode 中的别名 ID 转成目标路径。示例故意设置三项错误。
# 源端已映射成 Figma 目标类型;单位另存在同步映射表中。
source = {
'color.brand.600': {'type': 'COLOR', 'value': '#2359C4'},
'color.action.primary': {'type': 'COLOR', 'alias': 'color.brand.600'},
'space.card.padding': {'type': 'FLOAT', 'value': 16},
}
# 模拟已归一化的 Figma 抽取结果,而非 API 原始 JSON。
figma = [
{'name': 'color/brand/600', 'type': 'COLOR', 'value': '#2359C4'},
{'name': 'color/action/primary', 'type': 'COLOR', 'value': '#2359C4'},
{'name': 'space/card/padding', 'type': 'STRING', 'value': '16'},
{'name': 'Color/Brand/600', 'type': 'COLOR', 'value': '#2359C4'},
]
index = {}
for row in figma:
path = row['name'].replace('/', '.').casefold()
if path in index:
print('NAME_COLLISION', path)
else:
index[path] = row
for path, expected in source.items():
actual = index.get(path)
if actual is None:
print('MISSING', path)
continue
if expected['type'] != actual['type']:
print('TYPE_MISMATCH', path, expected['type'], '!=', actual['type'])
continue
# 比较别名目标,而不是比较解析后的显示色值。
if expected.get('alias') != actual.get('alias'):
issue = 'ALIAS_LOST' if expected.get('alias') and not actual.get('alias') else 'ALIAS_CHANGED'
print(issue, path)
continue
if expected.get('value') != actual.get('value'):
print('VALUE_DRIFT', path)预期输出:
NAME_COLLISION color.brand.600
ALIAS_LOST color.action.primary
TYPE_MISMATCH space.card.padding FLOAT != STRING这里只检查一种规范化视图。实际生产审计还要逐个 Mode 比较色域、alpha、单位与复合样式字段,并区分“确实丢失”与“经过许可的近似转换”。
按差异级别修复和验收
- 先清除命名冲突,固定
tokenPath与 Figmakey的映射;已有引用应在重命名后重新解析。 - 再修复错误类型与断开的
VARIABLE_ALIAS,检查目标变量存在且类型相容;复合样式中不能表达的字段列入人工审核,不许静默删除。 - 将 Figma 两个 Mode 分别对齐到
light、dark的 Resolver 输入。对color.action.primary同时检查解析色值和引用目标,对space.card.padding同时检查数值16与单位px。 - 用真实抽取数据替换示例快照,重跑审计。发布门槛是名称冲突、类型差异、别名差异、缺失项均为 0;允许的色彩近似必须列明色域、转换方式和误差。审核通过后再发布 Figma 库及工程产物。
即使两个按钮显示同一种蓝色,只要一个仍指向 color.brand.600、另一个已退化成硬编码,它们就不是等价的同步结果。