CSS变量失控主因是未分层设计：基础Token应统一定义在:root并带语义前缀，组件内只引用不声明；字号需分基础值与组件角色两级；暗色模式须用@media重置整套Token；外部项目需显式引入tokens.css并禁用CSS压缩的discardUnused。
为什么直接在组件里写 --color-primary 会失控
很多人一开始用 CSS 变量，是把 --color-primary、--spacing-md 直接塞进某个 Button 组件的 :root 或 .btn 里，结果很快发现：换主题时要改十几处，暗色模式要重写整套变量，第三方组件无法继承你的间距体系。根本问题不是变量没用，而是变量没分层——设计 Token 必须和使用上下文解耦。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 所有基础 Token（颜色、圆角、阴影、断点）只定义在
:root，且命名带语义前缀，比如--color-bg-surface而不是--bg-1 - 组件内部不声明新变量，只用
var(--color-bg-surface)；需要局部覆盖时，用属性选择器或自定义属性传入，例如button[data-variant="ghost"] { --color-bg-surface: transparent; } - 禁止在 SCSS/Less 中用
@mixin包裹变量赋值——那会切断运行时响应能力，CSS 变量的动态优势就废了
如何让 var(--font-size-sm) 在不同组件中真正“适配”而不是“硬套”
直接全局设 --font-size-sm: 0.75rem 看似省事，但 Card 标题用它会太小，Badge 用它又可能撑不开。关键不是调数值，而是定义相对关系：大小应由组件角色决定，而非固定像素。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 建立两级字号系统：基础 Token（
--font-size-100,--font-size-200）对应绝对值；组件 Token（--text-body-font-size,--text-caption-font-size）用var(--font-size-100)引用，便于统一缩放 - 在组件根元素上通过
font-size缩放整个子树，比如.badge { font-size: var(--font-size-100); }，其内部span就可用em或rem得到响应式缩放 - 避免在媒体查询里重复写
--font-size-sm，改用@media (min-width: 768px) { :root { --font-size-scale: 1.1; } }，再让组件用calc(var(--font-size-100) * var(--font-size-scale))
暗色模式切换时 color-scheme: only light 导致变量失效怎么办
Chrome 111+ 默认启用 color-scheme: light dark，但如果你在 :root 里只写了 --color-text: #333，系统切暗色时浏览器不会自动换值——CSS 变量不感知系统偏好，得手动桥接。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 用
@media (prefers-color-scheme: dark)重置整套 Token，不要只改几个颜色：:root { --color-text: #333; --color-bg: #fff; } @media (prefers-color-scheme: dark) { :root { --color-text: #e0e0e0; --color-bg: #1a1a1a; } } - 若需 JS 主动控制（如用户手动开关），别用
document.documentElement.style.setProperty()批量设几十个变量，改用切换 class：document.documentElement.classList.toggle('theme-dark')，然后用.theme-dark { --color-text: #e0e0e0; } - 注意 Safari 对
@media (prefers-color-scheme)的解析延迟：首次加载可能闪白，加<meta name="color-scheme" content="light dark">提前声明
组件库打包后 var(--shadow-lg) 在外部项目里报错“无效属性值”
这不是变量没定义，而是外部项目没引入你的 Token 文件，或者构建工具（如 Webpack + CSS Minimizer）把未使用的变量删掉了。CSS 变量不像 JS 模块有 tree-shaking 控制权，它们全靠引用链存活。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- Token 必须单独拆成
tokens.css并导出为独立入口，要求使用者显式引入：@import 'my-ui/tokens.css';，不能指望组件 CSS 里@import它 - Webpack 构建时禁用 CSS Minimizer 的
discardUnused（默认开启），否则未被当前 CSS 文件直接引用的变量会被清除 - 在组件库文档里明确写清依赖顺序：必须先载入
tokens.css，再载入button.css，否则变量查不到会回退到initial值，导致布局塌陷
最常被忽略的一点：CSS 变量作用域是继承的，但 display: none 的元素依然参与继承链——别指望隐藏组件能“隔离”变量污染，要用 all: unset 或 scoped class 显式重置。
