UI 视觉设计 / 系统课时

按语义版本发布 Token 资源包

按语义版本发布 Token 资源包

把生成好的 CSS 变量、ESM 常量和类型声明发布为可追踪的 npm 版本。本篇以资源包从 1.4.2 升级到 1.5.0 为例,完成兼容性判级、版本和变更记录更新、发布预检,以及组件项目中的锁定、升级与回退。

学习目标

  • 根据公开 Token 名称、类型与导出路径选择 PATCH、MINOR 或 MAJOR。
  • 更新包版本与 CHANGELOG.md,检查发布内容并完成 npm 发布。
  • 在组件项目中锁定指定版本、验证升级,并在出现样式回归时恢复旧版。

按公开契约判定版本级别

将组件能使用的 CSS 自定义属性名、ESM 导出、TypeScript 类型以及 package.json 的 exports 路径视为公开契约。以已发布的 1.4.2 为基线,按兼容性而不是修改文件数判级。

实际改动 级别 下一个版本
修正 --color-action-primary 的错误回退值,旧引用仍可用 PATCH 1.4.3
新增 --color-action-secondary,保留原属性 MINOR 1.5.0
删除或改名 --color-action-primary,旧组件样式失效 MAJOR 2.0.0

一次发布包含多种改动时,采用破坏性最高的级别。即使变量名不变,品牌颜色改变仍可能令截图或文字对比度发生变化,不能只凭类型检查判断安全;应对 Light、Dark 主题做视觉回归。0.x.y 属于尚未承诺稳定 API 的阶段,正式依赖方宜先明确兼容政策。判断规则参见 SemVer 2.0.0。

Token 兼容性变更的版本决策流程

配置包入口和变更记录

以下以 npm CLI 10~12 和已有 dist/index.js、dist/index.d.ts、dist/tokens.css 的项目为例。@your-scope/design-tokens 是示例包名,实际发布前必须换成自己拥有权限的 npm scope;发布者须登录相应 registry。

package.json 保留可验证的公开入口,并只把构建产物纳入包:

json
{
  "name": "@your-scope/design-tokens",
  "version": "1.4.2",
  "type": "module",
  "files": ["dist"],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./tokens.css": "./dist/tokens.css"
  },
  "publishConfig": {
    "access": "public"
  }
}

这是发布清单示例,不会自行生成 dist。在 CHANGELOG.md 为即将发布的 1.5.0 记录日期 2026-10-19、Added:新增 --color-action-secondary、Compatibility:原有变量与导出路径不变、Migration:旧组件无须改代码,新组件按需使用新增变量。若属于 MAJOR,必须具体列出旧名称、新名称和迁移步骤。

预检并发布新版本

先生成并检查 dist,确保类型声明、CSS 与 ESM 来自同一份 Token 源数据;确认本次没有误打包密钥或本地配置。这里选 MINOR,且禁用 npm version 自动创建 Git 提交和标签,便于先审阅变更记录。

bash
npm version minor --no-git-tag-version
npm pack --dry-run

预期结果:npm version 输出 v1.5.0,并更新 package.json,存在 package-lock.json 时同步更新其中版本;npm pack --dry-run 的文件清单包含 dist/index.js、dist/index.d.ts、dist/tokens.css。如果缺文件或版本不一致,先修复构建,不要发布。

bash
npm publish --dry-run --access public

预期结果:展示拟发布文件与 1.5.0 包信息,不会上传包。审核无误后,将版本文件、变更记录和锁文件提交到 Git,再对对应提交打 v1.5.0 标签;有发布权限、已完成必要身份验证时执行:

bash
npm publish --access public
npm view @your-scope/design-tokens@1.5.0 version

预期结果:发布成功后查询返回 1.5.0。若权限或认证失败,发布不会成功,应检查 scope 权限、registry 与登录状态。已发布的同名同版本不能覆盖,修复必须使用新版本号,具体规则可参考 npm publish 文档。

在组件项目锁版并验证升级

在独立组件项目根目录先安装旧版;下面的命令以示例包已在 registry 中发布为前提。

bash
npm install --save-exact @your-scope/design-tokens@1.4.2
npm ls @your-scope/design-tokens

预期结果:依赖树显示 1.4.2;package.json 保存精确版本 1.4.2,没有 ^ 或 ~,同时更新 package-lock.json。提交两份文件后,CI 使用 npm ci,会严格按锁文件安装,且不改写锁文件。

bash
npm install --save-exact @your-scope/design-tokens@1.5.0
npm ls @your-scope/design-tokens

预期结果:依赖树显示 1.5.0,声明版本和锁文件同时升级。在已有 CSS 导入 @your-scope/design-tokens/tokens.css 的组件项目中,运行项目原有构建与视觉回归检查,至少比较 Light、Dark 各自的 Default、Hover、Disabled,共六组按钮基线。确认新增变量可用且旧引用、类型检查和页面样式不受影响,再合并升级提交。

出现回归时回退消费者

假设升级后 Dark 模式的 Primary 按钮文字对比度由 5.1:1 降为 3.2:1,不满足普通文字 4.5:1 的 WCAG AA 对比度要求。先把受影响组件项目恢复到已验收版本:

bash
npm install --save-exact @your-scope/design-tokens@1.4.2
npm ls @your-scope/design-tokens

预期结果:依赖树重新显示 1.4.2;重新运行构建和六组视觉基线后,应恢复旧版样式,并将回退后的 package.json 与 package-lock.json 一起提交。

若 1.5.0 已发布且被确认有缺陷,维护者可在拥有发布权限时标记弃用,而不是删包再用相同版本重发:

bash
npm deprecate @your-scope/design-tokens@1.5.0 "Dark theme regression; use 1.4.2"

预期结果:registry 将该版本标记为 deprecated,后续安装它的用户会收到弃用警告;版本内容不会被改写。随后修复对比度并以新版本发布,不能覆盖原来的 1.5.0。

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

目录与阅读设置

阅读设置

17

记录一个想法

按语义版本发布 Token 资源包

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

登录哪都通