UI 视觉设计 / 系统课时
校验导出数据的缺失与循环引用
校验导出数据的缺失与循环引用
变量导出成功并不代表令牌可以安全进入构建:同一路径可能被覆盖,别名可能指向不存在的目标,还可能出现类型冲突或引用环。本课用一个可运行的校验器识别这四类问题,并让错误在生成 Web、Android、iOS 产物前中断流水线。
学习目标
- 区分重名路径、未解析别名、类型不匹配和循环引用。
- 使用 Python 标准库检查令牌依赖并返回可供 CI 识别的退出码。
- 知道校验器接入实际导出流程时需要补齐哪些边界。
先确定校验输入和失败规则
不要直接把 Figma 变量名称塞进 JSON 对象:对象构造时,重复键可能已经覆盖旧值,之后就查不到重名证据。先选定一个品牌与主题模式,将每条导出记录整理为 path、$type、$value,并保留重复记录;同一输出作用域内的路径必须唯一。
| 检查项 | 错误样例 | 处理方式 |
|---|---|---|
| 重名路径 | 两条 color.action.primary |
报错,禁止后者覆盖前者 |
| 未解析别名 | {color.gray.500} 不存在 |
报告源路径和缺失目标 |
| 类型不匹配 | color 别名指向 dimension |
比较已确定的类型 |
| 循环引用 | A 引用 B,B 再引用 A | 报告完整闭环并阻断构建 |
这里的 $type 是已经确定的有效类型:导出适配层须先处理组级类型继承;没有显式类型的别名,也可能从最终目标推导类型。不同主题模式中复用同一路径不应被误判为重名,应分别校验各模式的最终输出。
从别名建立依赖图
对完整形如 {color.brand.600} 的 $value,建立从当前令牌指向目标令牌的依赖边。查不到目标时报告缺失;找到目标后比较有效类型。最后使用深度优先搜索:节点处于“正在访问”状态时又被走到,就存在循环;已经访问完成的节点无需重复遍历。

运行最小校验器
以下代码适用于 Python 3.9 及以上版本,仅依赖标准库。默认内置一组含四类错误的演示记录;传入文件路径时则读取扁平 JSON 数组。样例颜色使用 DTCG 的 colorSpace/components 对象,尺寸使用 value/unit 对象,而不是把 8px 当成 DTCG dimension 原始值。
保存为 validate_tokens.py:
import json
import re
import sys
from pathlib import Path
SAMPLE = [
{"path": "color.brand.600", "$type": "color",
"$value": {"colorSpace": "srgb", "components": [0, 0.4, 0.8]}},
{"path": "color.action.primary", "$type": "color",
"$value": "{color.brand.600}"},
{"path": "color.action.primary", "$type": "color",
"$value": "{color.brand.600}"},
{"path": "space.2", "$type": "dimension",
"$value": {"value": 8, "unit": "px"}},
{"path": "button.padding", "$type": "color", "$value": "{space.2}"},
{"path": "text.muted", "$type": "color", "$value": "{color.gray.500}"},
{"path": "color.loop.a", "$type": "color", "$value": "{color.loop.b}"},
{"path": "color.loop.b", "$type": "color", "$value": "{color.loop.a}"},
]
def validate(records):
index, errors = {}, []
# 建索引前找重名,避免覆盖已导出的记录。
for token in records:
path = token["path"]
if path in index:
errors.append(f"DUPLICATE {path}")
else:
index[path] = token
links = {}
for path, token in index.items():
value = token["$value"]
if not isinstance(value, str):
continue
# 此最小示例只识别完整值别名 {token.path}。
match = re.fullmatch(r"\{([^{}]+)\}", value)
if not match:
continue
target = match.group(1)
if target not in index:
errors.append(f"UNRESOLVED {path} -> {target}")
continue
target_type = index[target]["$type"]
if token["$type"] != target_type:
errors.append(
f"TYPE_MISMATCH {path}: {token['$type']} != {target_type}"
)
links[path] = target
state = {}
def visit(path, trail):
# 1 表示搜索栈内,2 表示已完成。
if state.get(path) == 1:
cycle = trail[trail.index(path):] + [path]
errors.append("CYCLE " + " -> ".join(cycle))
return
if state.get(path) == 2:
return
state[path] = 1
if path in links:
visit(links[path], trail + [path])
state[path] = 2
for path in index:
if path not in state:
visit(path, [])
if errors:
print("\n".join(errors))
print(f"FAIL {len(errors)} issue(s); build blocked")
return 1
print(f"PASS {len(index)} tokens")
return 0
if __name__ == "__main__":
# 无参数跑内置样例;有参数则检查外部扁平 JSON 数组。
records = (json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
if len(sys.argv) == 2 else SAMPLE)
sys.exit(validate(records))运行 python3 validate_tokens.py。预期输出:
DUPLICATE color.action.primary
TYPE_MISMATCH button.padding: color != dimension
UNRESOLVED text.muted -> color.gray.500
CYCLE color.loop.a -> color.loop.b -> color.loop.a
FAIL 4 issue(s); build blocked退出码为 1。修复样例时,删除重复记录,把 button.padding 的类型改为 dimension,将 text.muted 和 color.loop.b 都改为引用 {color.brand.600}。再次运行应显示 PASS 7 tokens,退出码为 0。
在构建前设置校验门禁
实际接入时,先把 Figma 导出结果归一化为一组扁平记录,再运行 python3 validate_tokens.py tokens.flat.json。CI 只在退出码为 0 时继续执行原有的令牌转换与组件构建步骤;出现任意错误就停止,避免 Web 与移动端产物各自吞掉不同的坏数据。
这份脚本专门演示完整值别名的四类校验,并不是 DTCG 全量验证器。正式使用还要校验原始 $value 的类型结构、组继承与模式展开,并覆盖复合值内部引用、$ref 和 $extends 的解析及环检测;可对照 DTCG Format 2025.10 完成适配。