不能直接在libs/ui里写CSS变量，因Nx不将其视为可构建资产，导致依赖丢失、缓存失效；同名变量冲突使runtime行为不可控；应改用JSON+TS类型双输出，并通过构建插件注入:root生效。
为什么不能直接在 libs/ui 里写 CSS 变量？
因为 Nx 默认不把 CSS 文件当作“可构建的输出资产”纳入项目依赖图。你在 libs/ui 里放一个 tokens.css，apps/web 直接 @import 或 link 它，Nx 不会感知这个依赖关系 —— 构建时不会自动复制、不会触发重构建、缓存也会失效。更麻烦的是，CSS 变量本身没有模块作用域，一旦多个项目各自定义同名 token（比如 --color-primary），最终 runtime 行为不可控。
libs/tokens 应该导出什么？
必须导出可被 TypeScript 消费的结构化数据，而不是原始 CSS。推荐用 JSON + TS 类型双输出：
- 主文件：
libs/tokens/src/lib/tokens.json（纯数据，含注释和嵌套结构） - 类型定义：
libs/tokens/src/lib/tokens.type.ts（自动生成或手写export type TokenSet = { color: { primary: string } }） - 构建产物：
dist/libs/tokens/tokens.json和dist/libs/tokens/index.d.ts（由project.json中的buildtarget 生成）
这样 apps/web 就能通过 import { tokens } from '@bitwarden/tokens' 安全引用，TypeScript 提供补全和校验，Nx 也能正确识别依赖链。
如何让 CSS 变量真正生效到浏览器？
靠构建时注入，而不是运行时加载。在 apps/web 的构建流程中（比如 Vite 或 Webpack），用插件读取 dist/libs/tokens/tokens.json，动态生成 :root 块并写入最终 CSS。示例（Vite 插件片段）：
立即学习“前端免费学习笔记（深入）”；
export default function tokensPlugin() {
return {
name: 'inject-tokens',
transformIndexHtml: () => ({
tag: 'style',
attrs: { type: 'text/css' },
children: generateCssVariables(
JSON.parse(
fs.readFileSync('dist/libs/tokens/tokens.json', 'utf8')
)
),
}),
};
}
关键点：generateCssVariables() 必须递归扁平化嵌套 JSON，把 { color: { primary: '#007bff' } } 转成 --color-primary: #007bff；且该插件必须在 css 处理阶段之前执行，否则会被 PostCSS 优化掉。
多人协作时最容易忽略的坑
Token 命名变更不是“改个字符串”那么简单：
- JSON 文件里的 key 改了，
tokens.type.ts必须同步更新，否则所有引用处报 TS 错误 - 如果旧 token 被其他项目直接用了 CSS 变量（比如
color: var(--old-token-name)），光改 JSON 不够，还得加 alias 映射或发 breaking change 提示 - Nx 缓存默认不监听
.json文件变更 —— 要在project.json的buildtarget 里显式配置"inputs": ["{projectRoot}/src/lib/**/*.json"]，否则改了 token 内容，nx build web仍会命中缓存
真正的统一，不在文件位置，而在构建链路是否把 token 当作一等公民参与依赖解析与缓存决策。
