多品牌 Design Tokens 跨仓库分发利用 NPM 私有作用域包与语义化版本在拥有多条独立业务线、跨国子品牌或多端矩阵Web/SaaS、iOS、Android、小程序的中大型科技企业中设计系统Design System最令人头痛的瓶颈从来不是“画出一套好看的 UI 组件”而是如何将成千上万个跨品牌的设计变量Design Tokens以安全、可控、高保真的方式分发给数十个独立的业务代码仓库。在缺乏基础设施支持的团队里常见的“原始分发”方式惨不忍睹要么是设计师在飞书或 Slack 群里发一份 JSON 文件前端工程师手动复制粘贴到项目常量文件里要么是各个业务线自己维护一套 CSS 变量品牌主色一旦微调全集团十几位前端要花两三天人工核对代码。更可怕的是某个业务线悄悄把--color-primary的十六进制改了另一个团队重命名了 Token 键名最终导致线上界面五花八门、破坏性变更频发。为了彻底打通设计与工程的“最后一公里”我们在内部搭建了一套基于**单源定义Single Source of Truth、Style Dictionary 跨端编译、NPM 私有作用域包Scoped Packages与严格语义化版本SemVer**的 Tokens 自动化分发体系。本文将全景拆解这套工业级基础设施的架构设计与核心实现。架构拓扑多层级 Tokens 继承与分发矩阵设计系统的变量不能扁平地混为一谈必须遵循严格的三层继承架构[全局基准层 Global/Primitive Tokens] - 基础色谱 (如 blue-500, gray-100) - 基础空间阶梯 (如 space-4, space-8) - 基础字体与圆角 │ ▼ 继承与映射 [品牌语义层 Semantic Tokens (按品牌与主题分发)] - 品牌 A (白天/暗黑): --color-bg-brand - blue-500 - 品牌 B (海外轻量): --color-bg-brand - purple-600 │ ▼ 消费与覆盖 [组件级 Tokens Component Tokens] - --btn-primary-bg - --color-bg-brand - --card-radius - --radius-md私有作用域分包设计在 NPM 私有仓库如 Verdaccio、GitHub Packages 或私有 Nexus中我们将 Tokens 拆解为细粒度的包簇company-ds/tokens-core包含纯粹的数学尺度、基础色阶等跨品牌共享的原语常量company-ds/tokens-brand-a品牌 A 的专用语义包输出该品牌专属的 CSS/SCSS/TS 产物company-ds/tokens-brand-b品牌 B 的专用语义包company-ds/tokens-cli用于在业务项目构建时进行 Token 类型校验和无效引用扫描的工程插件。编译引擎基于 Style Dictionary 的多端跨平台转化所有的 Token 源文件统一以标准化 JSON / JSON5 格式存储在专门的设计系统 Git 仓库中。利用开源编译工具Style Dictionary我们可以将单源 JSON 自动化编译为多端所需的物理产物// style-dictionary.config.js import StyleDictionary from style-dictionary; export function buildBrandTokens(brandName, theme light) { const sd new StyleDictionary({ source: [ tokens/global/**/*.json, tokens/brands/${brandName}/${theme}/**/*.json ], platforms: { css: { transformGroup: css, buildPath: dist/css/, files: [{ destination: ${brandName}-${theme}.css, format: css/variables, options: { selector: :root[data-brand${brandName}][data-theme${theme}], outputReferences: true // 保留变量引用关系 } }] }, typescript: { transformGroup: js, buildPath: dist/ts/, files: [{ destination: ${brandName}-${theme}.ts, format: javascript/es6 }, { destination: ${brandName}-${theme}.d.ts, format: typescript/es6-declarations }] }, json: { transformGroup: web, buildPath: dist/json/, files: [{ destination: ${brandName}-${theme}.json, format: json/flat }] } } }); sd.buildAllPlatforms(); }契约之魂Tokens 维度的语义化版本SemVer裁定规则将代码库发布到 NPM 很容易难的是如何界定一次 Token 变更是属于 Patch、Minor 还是 Major如果把语义化版本完全交给工程师的主观感觉极易发生灾难例如某位开发者只是把某个不再使用的 Token 给删除了随手发了一个1.0.1Patch结果全公司下游 30 多个业务线在夜间执行npm update时全都在打包编译阶段报 TypeScript 找不到属性的致命错误。我们在 CI 流水线中通过 AST 差异比对Token Schema Diff强制执行以下语义化版本裁定铁律变更类型触发场景举例版本号推进自动化 CI 行为Patch (修订版)纯视觉参数修正将--color-primary从#1677ff微调为#1668e3尺寸数值微调不改变类型修复文档注释v1.2.0 - v1.2.1业务线可自动安全升级不影响类型和布局拓扑Minor (次版本)向后兼容的新增新增--color-warning-soft增加新的圆角阶梯--radius-3xlv1.2.0 - v1.3.0业务线无感知兼容允许平滑试用新变量Major (主版本)破坏性变更删除已有 Token重命名 Token 键名改变变量的量纲如将纯数字改为包含 px 的字符串v1.2.0 - v2.0.0严禁自动升级CI 生成自动化迁移 Codemod 脚本并在 Release 中置顶警示跨仓库自动化消费实战业务端优雅接入在下游业务项目如使用 Next.js 或 Vite 构建的企业级 SaaS 平台中工程师通过常规 NPM 方式安装对应品牌的私有包pnpm add company-ds/tokens-brand-a1. 样式层无缝注入在应用入口文件如_app.tsx或main.ts中直接引入编译好的原生 CSS 变量样式表// main.ts import company-ds/tokens-brand-a/dist/css/brand-a-light.css; import company-ds/tokens-brand-a/dist/css/brand-a-dark.css;在业务 CSS 模块中工程师享有百分之百的纯原生支持与现代化语法补全/* button.module.css */ .actionButton { background-color: var(--color-brand-primary); border-radius: var(--radius-md); padding: var(--space-2) var(--space-4); color: var(--color-text-on-brand); transition: background-color 0.2s cubic-bezier(0.16, 1, 0.3, 1); } .actionButton:hover { background-color: var(--color-brand-primary-hover); }2. TypeScript 类型安全感知与动态计算在需要动态绘制 Canvas 图表或通过 WebGL 渲染三维材质的场景下直接引入经过强类型约束的 TypeScript 常量// chartRenderer.ts import { BrandALightTokens } from company-ds/tokens-brand-a; export function renderPerformanceChart(ctx: CanvasRenderingContext2D) { // 享有 IDE 自动补全与类型推导保护 ctx.strokeStyle BrandALightTokens.colorBrandPrimary; ctx.lineWidth BrandALightTokens.strokeWidthThin; // ... }生产级防护CI 流水线中的无效引用扫描器除了发布与消费我们还在业务仓库的 Git Pre-commit 钩子及 CI 流水线中植入了一个轻量级静态扫描脚本。该脚本基于 PostCSS 解析业务代码中的所有var(--...)声明并与当前依赖的company-ds/tokens-*包中导出的白名单进行集合交集检查// checkTokensA11y.ts import { readFileSync } from fs; import { validTokenKeys } from company-ds/tokens-brand-a/meta; export function lintCssVariables(cssContent: string) { const varRegex /var\((--[a-zA-Z0-9_-])\)/g; let match: RegExpExecArray | null; const invalidTokens: string[] []; while ((match varRegex.exec(cssContent)) ! null) { const tokenName match[1]; // 如果是以集团规范命名的 token但不在官方发布的白名单中 if (tokenName.startsWith(--color-) || tokenName.startsWith(--space-)) { if (!validTokenKeys.has(tokenName)) { invalidTokens.push(tokenName); } } } if (invalidTokens.length 0) { console.error( 检测到非法或已废弃的 Design Tokens 引用:\n${invalidTokens.join(\n)}); process.exit(1); } }如果某个业务同学在 CSS 里随手拼错了一个字母如写成var(--color-brand-prmary)CI 门禁将立即拦截构建并给出明确报错彻底杜绝了因拼写失误导致的线上视觉白屏或样式降级事故。通过“单源配置 - 工业级跨端构建 - 语义化 NPM 作用域分发 - 严格版本约束 - 静态门禁扫描”这套闭环机制多品牌设计系统从感性的设计图稿蜕变为严谨、可被自动化版本控制的现代软件工程资产。