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:

python
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。预期输出:

text
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 完成适配。

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

目录与阅读设置

阅读设置

17

记录一个想法

校验导出数据的缺失与循环引用

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

登录哪都通