UI 视觉设计 / 系统课时
迁移废弃变量并保留兼容入口
迁移废弃变量并保留兼容入口
当组件仍在使用旧 Token,而规范已经启用新的语义名称时,直接删除旧路径会使下游样式或类型导出失效。本课以按钮背景色迁移为例,把旧变量改成指向新变量的兼容别名,标记弃用原因,并用自动检查和分阶段发布完成替换。
学习目标
- 判断旧 Token 能否安全映射到新语义,列出必须保留的外部入口。
- 使用 DTCG 的
$deprecated和别名语法保留旧路径,避免维护两份色值。 - 验证引用解析和生成产物,制定可执行的下线条件。
清点旧引用并确定迁移边界
假设旧路径是 color.button.primaryBg,希望统一为 color.action.primary。先在设计源文件、组件库源码、业务仓库中搜索两个 Token 路径,再搜索已发布 CSS 名称 --color-button-primary-bg。若 TypeScript 包也曾导出旧属性,应一并登记其使用方;只修改源 JSON 并不能自动保证所有公开接口兼容。
判断两者是否能合并,要比较用途而不只比较当前颜色:旧路径如果专门表示按钮的禁用态,就不能直接别名到普通操作主色。至少在 Light、Dark 以及项目实际发布的品牌主题下,确认替代关系一致。对于确认同义的路径,迁移计划如下:
| 发布阶段 | 源文件与产物 | 消费方动作 |
|---|---|---|
| v2.4.0 | 增加新 Token,旧 Token 标记弃用并保留输出 | 公布替代路径,旧调用继续可用 |
| v2.5.0 | 同时发布新旧入口 | 替换组件库内部及已知业务引用,禁止新增旧引用 |
| v3.0.0 | 满足迁移条件后才移除旧入口 | 升级前确认外部调用方已迁移;若未完成则延后删除 |
此版本号是示例发布计划,不是 DTCG 强制规定。删除曾公开发布的名称属于破坏性变更,应按项目的语义化版本策略发布。
在源 Token 中保留旧名称
DTCG 2025.10 允许使用 $deprecated 标记 Token,可设为 true 或描述原因的字符串;$value 使用 {color.action.primary} 引用另一 Token。把下列内容保存为 tokens/tokens.json:
{
"color": {
"action": {
"primary": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0.08235, 0.36863, 0.93725],
"hex": "#155eef"
}
}
},
"button": {
"primaryBg": {
"$type": "color",
"$value": "{color.action.primary}",
"$deprecated": "改用 color.action.primary;计划在 v3.0.0 移除。"
}
}
}
}这使旧路径与新路径解析到同一个颜色对象,后续改色只需改新 Token。$deprecated 是元数据,不会自动删除旧 Token,也不保证生成器一定发出弃用警告;必须检查实际使用的构建工具是否保留旧路径,以及文档或类型声明是否单独暴露弃用信息。

用脚本锁定别名兼容契约
在 Node.js 22 或更高版本的项目中,将下列脚本保存为 scripts/check-deprecated.mjs。它验证旧 Token 仍存在、已写明弃用原因、类型匹配且别名指向新路径;递归解析时也会拒绝循环引用。
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
const source = JSON.parse(readFileSync("tokens/tokens.json", "utf8"));
const oldPath = "color.button.primaryBg";
const newPath = "color.action.primary";
// 根据路径读取叶子 Token,缺失时立即失败。
function tokenAt(path) {
const node = path.split(".").reduce((value, key) => value?.[key], source);
assert.ok(node && typeof node === "object" && "$value" in node, `Token 缺失:${path}`);
return node;
}
// 只解析本示例使用的整值别名,同时防止循环引用。
function resolvedValue(path, visited = new Set()) {
assert.ok(!visited.has(path), `循环引用:${path}`);
visited.add(path);
const value = tokenAt(path).$value;
if (typeof value === "string" && value.startsWith("{") && value.endsWith("}")) {
return resolvedValue(value.slice(1, -1), visited);
}
return value;
}
const oldToken = tokenAt(oldPath);
const newToken = tokenAt(newPath);
assert.equal(oldToken.$value, `{${newPath}}`);
assert.equal(oldToken.$type, newToken.$type);
assert.ok(typeof oldToken.$deprecated === "string");
assert.ok(oldToken.$deprecated.includes(newPath));
assert.deepEqual(resolvedValue(oldPath), resolvedValue(newPath));
console.log("PASS: 旧 Token 已弃用且别名解析一致");在项目根目录执行:
node scripts/check-deprecated.mjs预期输出:
PASS: 旧 Token 已弃用且别名解析一致把旧 Token 的 $value 临时改成不存在的路径再运行,脚本应以非零退出码失败。该脚本检查源 Token;真正的发布流程还必须在编译之后检查产物是否保留旧名称。
验收生成产物并逐步移除旧入口
对于将点路径转换为 CSS 自定义属性的项目,构建后的 generated/tokens.css 应能查到 --color-action-primary 和 --color-button-primary-bg。如果生成器支持并启用了保留变量引用,兼容声明可能呈现为以下形式(片段示例,不代表所有生成器默认输出):
:root {
--color-action-primary: #155eef;
--color-button-primary-bg: var(--color-action-primary);
}生成器也可能把两个变量都输出为同一最终色值;关键是旧名称仍存在、值相同,且升级后现有样式不报错。组件库的新代码应统一改用 var(--color-action-primary),但暂时不要从构建配置中过滤旧 Token。若包还公开了 TypeScript 常量、类型或 Figma 别名,需分别验证旧标识依然可解析,不能把 CSS 兼容当作全部兼容。
发布前逐项确认:新旧变量在每个主题下取值一致;构建后的 CSS 和类型入口未丢失;内部搜索已没有旧路径的新引用;迁移说明写明替代名称和预计移除版本。外部消费者是否迁移不能仅凭本仓库搜索推断,必要时先进行一次主要版本的弃用公告与兼容观察。只有公开消费方的迁移范围已确认、破坏性变更已沟通且回归测试通过,才在后续主版本删除旧别名。