UI 视觉设计 / 系统课时
处理令牌更名时的兼容引用
处理令牌更名时的兼容引用
将 color.button.primary 更名为 color.action.primary 后,删除旧名可能破坏旧组件。本文用“新名存值、旧名做别名”同步迁移 Figma 变量及代码消费方,并通过版本门禁判断何时能够安全移除。
学习目标
- 判断哪些更名会破坏设计绑定或代码接口。
- 在 Figma 与 DTCG 令牌中保留单向兼容别名。
- 找出旧名使用者,安排弃用版本并验证安全移除。
判断哪些引用会受影响
假设旧名称是 color.button.primary,新名称是 color.action.primary。先核对两者是否确实表达同一语义:如果旧名只服务按钮、新名将服务全部操作控件,就必须确认未来改色时两者也应该一起变化;否则应保留两个独立令牌,而不是强行建立别名。
| 所在层 | 旧入口 | 迁移后的入口 | 风险点 |
|---|---|---|---|
| Figma 变量 | color/button/primary |
color/action/primary |
设计文件仍绑定旧变量 |
| DTCG 源文件 | color.button.primary |
color.action.primary |
旧路径被其他 Token 引用 |
| Web 构建产物 | --color-button-primary |
--color-action-primary |
样式表仍使用旧 CSS 变量 |
| App 构建产物 | 如 colorButtonPrimary |
如 colorActionPrimary |
生成常量或跨仓库依赖未升级 |
App 常量名只是命名转换示例,应以项目实际生成文件为准。兼容期要同时保留旧入口和新入口,不能只在 Figma 改名后就认为代码已迁移。
让旧名单向引用新名
在 Figma 变量库中,不要先删除原变量。按以下顺序操作:
- 在原 Collection 新建 Color 变量
color/action/primary,示例 Light 值设为#2563EB,Dark 值设为#60A5FA。 - 保留
color/button/primary原有变量及其绑定;在 Variables 弹窗中右键旧变量的值,选择Create alias,指向新变量。检查每个 Mode 下的值均由新变量提供。 - 在旧变量 Description 中注明“Deprecated:改用 color/action/primary,预计 v2.0.0 移除”;兼容期间继续发布旧变量,不要隐藏或删除。
- 发布 Library 更新,让下游文件审查并应用更新;随机抽查一个仍绑定旧变量的按钮,确认 Light 和 Dark 外观不变。操作位置见 Figma 变量管理说明。
代码端也需保留同样的引用方向。下面是 tokens/light.json 的 DTCG 2025.10 片段示例;Dark 主题文件应以同样方式设置旧名别名,仅新名色值不同。
{
"color": {
"action": {
"primary": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0.145098, 0.388235, 0.921569],
"hex": "#2563EB"
}
}
},
"button": {
"primary": {
"$type": "color",
"$value": "{color.action.primary}",
"$deprecated": "请改用 color.action.primary;计划在 v2.0.0 删除"
}
}
}
}**验证方法:**使用现有令牌构建器解析引用,检查 Light 模式的新旧令牌均得到 #2563EB;Dark 模式均得到 #60A5FA。同时核对生成的 CSS 及 App 资源确实保留旧导出名称。$deprecated 是 DTCG 2025.10 规范中的元数据,不等于所有构建器都会自动报警;不要依赖它替代扫描和版本公告。

扫描消费方并登记责任人
以下脚本使用 Node.js 18 或更新版本的内置模块,保存为 tools/audit-legacy.mjs,在仓库根目录执行 node tools/audit-legacy.mjs。它递归扫描常见源码目录,输出含旧名的文件和行号;按项目实际生成规则补充 legacyNames,不要把 dist 等构建产物计入源码迁移数量。
import { existsSync, readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
// 旧名称可能被转换为不同平台的导出标识符。
const legacyNames = [
"color.button.primary",
"--color-button-primary",
"colorButtonPrimary",
"color_button_primary"
];
const roots = ["src", "packages", "docs", "tokens", "ios", "android"];
const excluded = new Set(["node_modules", "dist", "build", ".git"]);
const supported = /\.(css|scss|js|jsx|ts|tsx|json|md|mdx|swift|kt|xml)$/;
const hits = [];
function scan(dir) {
if (!existsSync(dir)) return;
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const path = join(dir, entry.name);
if (entry.isDirectory()) {
if (!excluded.has(entry.name)) scan(path);
} else if (entry.isFile() && supported.test(entry.name)) {
const lines = readFileSync(path, "utf8").split(/\r?\n/);
lines.forEach((line, index) => {
if (legacyNames.some((name) => line.includes(name))) {
hits.push(`${path}:${index + 1}`);
}
});
}
}
}
roots.forEach(scan);
hits.sort().forEach((hit) => console.log(hit));
console.log(`旧名命中 ${hits.length} 行`);预期结果(示例仓库无旧名使用时):
旧名命中 0 行有命中时先输出 相对路径:行号,再打印非零总数;实际路径和数量取决于仓库。把结果整理为“仓库/负责人/旧名命中数/预计升级版本”,每次发布比较数量是否下降。还要检查其他消费仓库、Figma Library 使用者及运行时拼接的名称;单仓库文字扫描无法覆盖这些情况。
用版本窗口控制弃用与移除
以下是可执行的发布约定示例,日期与版本应由项目发布计划确定,不是 DTCG 强制规定。
| 阶段 | 发布约定 | 放行条件 |
|---|---|---|
| 兼容发布 | v1.8.0:增加新名、保留旧名别名和弃用说明 |
新旧值一致,各平台仍导出旧名 |
| 消费方迁移 | v1.9.x:兼容期累计至少 60 天 |
新代码禁止引入旧名,已登记仓库逐个升级 |
| 破坏性移除 | 不早于 v2.0.0:删除旧名 |
旧名命中为零,所有受支持消费方已确认兼容 |
正式移除前,必须分别构建 Light 与 Dark 主题,检查 Web 变量和 App 常量的产出,并在 Figma 下游文件验证变量绑定。还应检查别名不存在循环、旧名未成为其他 Token 的目标引用、消费方没有固定在依赖旧导出的版本。任何一项未通过,就继续保留兼容别名并延后移除;真正删除时在变更日志中列出旧名、新名、首次弃用版本及迁移办法。