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 变量库中,不要先删除原变量。按以下顺序操作:

  1. 在原 Collection 新建 Color 变量 color/action/primary,示例 Light 值设为 #2563EB,Dark 值设为 #60A5FA。
  2. 保留 color/button/primary 原有变量及其绑定;在 Variables 弹窗中右键旧变量的值,选择 Create alias,指向新变量。检查每个 Mode 下的值均由新变量提供。
  3. 在旧变量 Description 中注明“Deprecated:改用 color/action/primary,预计 v2.0.0 移除”;兼容期间继续发布旧变量,不要隐藏或删除。
  4. 发布 Library 更新,让下游文件审查并应用更新;随机抽查一个仍绑定旧变量的按钮,确认 Light 和 Dark 外观不变。操作位置见 Figma 变量管理说明。

代码端也需保留同样的引用方向。下面是 tokens/light.json 的 DTCG 2025.10 片段示例;Dark 主题文件应以同样方式设置旧名别名,仅新名色值不同。

json
{
  "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 等构建产物计入源码迁移数量。

js
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} 行`);

预期结果(示例仓库无旧名使用时):

text
旧名命中 0 行

有命中时先输出 相对路径:行号,再打印非零总数;实际路径和数量取决于仓库。把结果整理为“仓库/负责人/旧名命中数/预计升级版本”,每次发布比较数量是否下降。还要检查其他消费仓库、Figma Library 使用者及运行时拼接的名称;单仓库文字扫描无法覆盖这些情况。

用版本窗口控制弃用与移除

以下是可执行的发布约定示例,日期与版本应由项目发布计划确定,不是 DTCG 强制规定。

阶段 发布约定 放行条件
兼容发布 v1.8.0:增加新名、保留旧名别名和弃用说明 新旧值一致,各平台仍导出旧名
消费方迁移 v1.9.x:兼容期累计至少 60 天 新代码禁止引入旧名,已登记仓库逐个升级
破坏性移除 不早于 v2.0.0:删除旧名 旧名命中为零,所有受支持消费方已确认兼容

正式移除前,必须分别构建 Light 与 Dark 主题,检查 Web 变量和 App 常量的产出,并在 Figma 下游文件验证变量绑定。还应检查别名不存在循环、旧名未成为其他 Token 的目标引用、消费方没有固定在依赖旧导出的版本。任何一项未通过,就继续保留兼容别名并延后移除;真正删除时在变更日志中列出旧名、新名、首次弃用版本及迁移办法。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理令牌更名时的兼容引用

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

登录哪都通