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:

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,也不保证生成器一定发出弃用警告;必须检查实际使用的构建工具是否保留旧路径,以及文档或类型声明是否单独暴露弃用信息。

旧 Token 通过别名过渡到新 Token,并保留双入口

用脚本锁定别名兼容契约

在 Node.js 22 或更高版本的项目中,将下列脚本保存为 scripts/check-deprecated.mjs。它验证旧 Token 仍存在、已写明弃用原因、类型匹配且别名指向新路径;递归解析时也会拒绝循环引用。

js
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 已弃用且别名解析一致");

在项目根目录执行:

bash
node scripts/check-deprecated.mjs

预期输出:

text
PASS: 旧 Token 已弃用且别名解析一致

把旧 Token 的 $value 临时改成不存在的路径再运行,脚本应以非零退出码失败。该脚本检查源 Token;真正的发布流程还必须在编译之后检查产物是否保留旧名称。

验收生成产物并逐步移除旧入口

对于将点路径转换为 CSS 自定义属性的项目,构建后的 generated/tokens.css 应能查到 --color-action-primary 和 --color-button-primary-bg。如果生成器支持并启用了保留变量引用,兼容声明可能呈现为以下形式(片段示例,不代表所有生成器默认输出):

css
:root {
  --color-action-primary: #155eef;
  --color-button-primary-bg: var(--color-action-primary);
}

生成器也可能把两个变量都输出为同一最终色值;关键是旧名称仍存在、值相同,且升级后现有样式不报错。组件库的新代码应统一改用 var(--color-action-primary),但暂时不要从构建配置中过滤旧 Token。若包还公开了 TypeScript 常量、类型或 Figma 别名,需分别验证旧标识依然可解析,不能把 CSS 兼容当作全部兼容。

发布前逐项确认:新旧变量在每个主题下取值一致;构建后的 CSS 和类型入口未丢失;内部搜索已没有旧路径的新引用;迁移说明写明替代名称和预计移除版本。外部消费者是否迁移不能仅凭本仓库搜索推断,必要时先进行一次主要版本的弃用公告与兼容观察。只有公开消费方的迁移范围已确认、破坏性变更已沟通且回归测试通过,才在后续主版本删除旧别名。

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

目录与阅读设置

阅读设置

17

记录一个想法

迁移废弃变量并保留兼容入口

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

登录哪都通