UI 视觉设计 / 系统课时
选择组件包与令牌包的仓库结构
选择组件包与令牌包的仓库结构
设计系统同时维护 Figma 变量、组件、文档和示例应用时,仓库结构决定一次令牌修改能否被同步验证。以两款产品共用一套视觉规范为例,这里确定适合团队协作的包边界,并搭建一个可以直接运行的最小仓库。
学习目标
- 分清单仓、多仓与多包的区别,判断何时应拆仓。
- 规定 tokens、components、docs 和示例应用的依赖方向。
- 用 npm Workspaces 建立可运行的样板,并检查变更传播。
按协作成本选择仓库
“单仓”描述代码放在哪里,“多包”描述模块如何依赖和发布。单仓可以同时包含多个独立版本的软件包;不是把全部组件编译成一个包才叫单仓。
| 决策项 | 单仓多包(Monorepo) | 多仓(Multirepo) |
|---|---|---|
| 令牌改动影响组件 | 同一提交可修改并测试两包 | 需先发布令牌,再更新组件依赖 |
| 权限和审核 | 通常共享仓库权限,可用目录规则约束 | 可以按仓库独立授权 |
| CI 与版本 | 可按受影响包测试、各包分别发版 | 各仓流水线天然分离,但跨仓协同更多 |
| 适合情况 | 设计规范共同维护、经常跨包修改 | 负责人独立、权限隔离强、发布周期差异大 |
例如两款产品、一个设计小组、三位前端开发者,每周两次调整组件与变量,优先选择单仓多包:一次 PR 同时更新令牌、组件与示例。若外包团队只能访问特定组件源码,或者某包需要独立的合规审批,再考虑多仓。无论选哪种方式,代码仓库边界不等于 npm 包边界。
固定四个工作区的职责
建议把可复用产物放在 packages/,把消费这些产物的应用放在 apps/。下表的“依赖”指直接声明在对应 package.json 里的内部包,而不是开发机上恰好能找到的模块。
| 工作区 | 职责 | 内部依赖 | 发布策略 |
|---|---|---|---|
packages/tokens |
接收审查后的 Figma 变量,输出语义令牌 | 无 | 作为独立包发布 |
packages/components |
实现按钮等组件及公开接口 | @demo/tokens |
作为独立包发布 |
apps/docs |
展示用法、交互状态和迁移说明 | @demo/components |
部署站点,不发布 npm 包 |
apps/playground |
在接近产品的环境中做集成验证 | @demo/components |
部署或运行应用,不发布 npm 包 |

Figma 文件是设计源,不是运行时依赖。tokens 应提供稳定的语义名称,例如 colorPrimary,不要让组件直接读取 Figma 节点 ID。components 不能反向依赖 docs;应用也不应通过 ../../packages/components/ 直接读取内部源码。文档站若需要直接绘制令牌色板,应额外显式声明对 tokens 的依赖。
用 npm Workspaces 建立最小样板
以下命令适用于 Node.js 20+、npm 9+ 和 Bash,在空目录执行。示例使用 ES Module,仅验证包之间的导入关系和令牌传播,不假装已经实现可视化按钮或 Figma 自动同步。
set -e
mkdir -p ds-workspace/packages/{tokens,components} ds-workspace/apps/{docs,playground}
cd ds-workspace
# 根目录聚合工作区,不作为公共包发布。
cat > package.json <<'JSON'
{"name":"ds-workspace","version":"1.0.0","private":true,"workspaces":["packages/*","apps/*"],"scripts":{"check":"node apps/docs/index.mjs && node apps/playground/index.mjs"}}
JSON
cat > packages/tokens/package.json <<'JSON'
{"name":"@demo/tokens","version":"1.0.0","type":"module","exports":"./index.js"}
JSON
cat > packages/tokens/index.js <<'JS'
export const tokens = Object.freeze({
colorPrimary: '#2563eb',
radiusSm: '4px'
});
JS
# 组件通过包名引用令牌;不导入令牌包的内部路径。
cat > packages/components/package.json <<'JSON'
{"name":"@demo/components","version":"1.0.0","type":"module","exports":"./index.js","dependencies":{"@demo/tokens":"1.0.0"}}
JSON
cat > packages/components/index.js <<'JS'
import { tokens } from '@demo/tokens';
// 将令牌映射为组件公开的样式结果。
export function buttonStyle() {
return { backgroundColor: tokens.colorPrimary, borderRadius: tokens.radiusSm };
}
JS
# 应用是私有工作区,但仍要声明自己的直接依赖。
for app in docs playground; do
cat > "apps/$app/package.json" <<JSON
{"name":"@demo/$app","version":"1.0.0","private":true,"type":"module","dependencies":{"@demo/components":"1.0.0"}}
JSON
done
cat > apps/docs/index.mjs <<'JS'
import { buttonStyle } from '@demo/components';
console.log('docs radius:', buttonStyle().borderRadius);
JS
cat > apps/playground/index.mjs <<'JS'
import { buttonStyle } from '@demo/components';
console.log('playground primary:', buttonStyle().backgroundColor);
JS
# 安装并连接本地工作区,再从两个消费端验证。
npm install --silent
npm run --silent check预期输出:
docs radius: 4px
playground primary: #2563ebworkspaces 指定要链接的本地包,dependencies 才是允许消费的依赖声明;exports 限制包名可导入的公开入口。这些行为可对照 npm Workspaces 官方文档 与 Node.js 包入口文档。
用一次令牌变更检查边界
把 packages/tokens/index.js 中的 colorPrimary 从 #2563eb 改为 #1d4ed8,再次运行 npm run --silent check。第一行仍是 docs radius: 4px,第二行应变为 playground primary: #1d4ed8:组件无需复制颜色值,消费端就能获得改动。这只验证模块传播;真正的 UI 仓库还须增加构建、视觉回归和无障碍测试。
合并前检查三个门禁:令牌包不导入组件包;组件只通过包名导入令牌;文档与示例仅消费公开 exports。提交时保留根目录的 package-lock.json,CI 使用 npm ci 复现依赖。
发布时先发布令牌包,再发布声明了相应令牌版本的组件包,最后部署文档与示例。新增兼容令牌通常可升次版本;删除或重命名公共令牌需要评估主版本升级。若后来增加 React 与 Vue 两套组件实现,可分别拆成组件包,让它们共享令牌契约,而不是强行共享跨框架运行时代码。