稳定的CSS主题变量体系需分三层：基础值层（:root中纯数值）、语义令牌层（:root中用calc/var推导的业务含义变量）、组件专属层（组件选择器内带命名空间的局部变量），配合强制前缀命名、暗色模式媒体查询全覆盖及构建时禁用变量压缩。
稳定的 CSS 主题变量体系不是靠“多定义几个 --color-xxx”堆出来的，而是靠分层、命名、作用域和构建流程四者咬合形成的约束系统。变量一失控，换主题就等于重写样式。
变量必须严格分三层：基础值、语义令牌、组件专属
很多人把所有变量都塞进 :root，结果改一个 --primary 全站乱套。真正可控的结构是：
-
基础值层（只在
:root）：纯数值，不带业务含义，例如--size-unit: 4px、--color-black: #000000、--font-stack-sans: -apple-system, BlinkMacSystemFont -
语义令牌层（也在
:root，但用基础值计算）：带业务含义，供组件直接引用，例如--color-bg-surface、--space-md、--radius-lg—— 它们的值必须是calc()或var()表达式，不能写死像素或颜色字面量 -
组件专属层（在组件选择器内）：仅限该组件内部使用的变量，带命名空间，例如
.card { --card-padding: var(--space-md); }，禁止出现在:root中
命名必须带前缀且不可缩写
写 --bg 或 --p 看似省事，实际等于放弃维护权。浏览器不报错，但人会疯。正确做法是：
- 颜色类一律用
--color-{domain}-{role}，例如--color-button-primary-bg、--color-input-border-hover - 间距/尺寸类用
--space-{size}或--size-{domain}-{dimension}，例如--space-section-vertical、--size-avatar-sm - 禁止出现
--c1、--s2、--main-bg这类无上下文变量，CI 可加 ESLint 规则拦截
暗色模式切换必须用 @media (prefers-color-scheme: dark) 重置整套语义令牌
只在 [data-theme="dark"] 里改几个颜色，color-scheme: dark 启用后依然白屏——因为浏览器不会自动把 --color-text 映射成深色值。真正有效的做法是：
立即学习“前端免费学习笔记（深入）”；
- 在
:root中先定义亮色语义令牌，再用媒体查询覆盖整套值： @media (prefers-color-scheme: dark) { :root { --color-bg-surface: #121212; --color-text-primary: #e0e0e0; /* …其他全部重置 */ } }- 不要依赖 JS 动态写
document.documentElement.style.setProperty来模拟暗色模式，那会绕过系统级 color-scheme 检测，导致 macOS 的自动切换失效
构建时必须禁用 CSS 压缩器的 discardUnused 选项
Webpack 的 css-minimizer-webpack-plugin 或 Vite 的 esbuild 默认会删掉“未使用”的 CSS 变量——但它无法识别 var(--color-bg-surface) 是否被 JS 或其他 CSS 引用，一删就全黑屏。必须显式关闭：
- Webpack：在
minimizer配置中加discardUnused: false - Vite：若用
build.cssMinify: 'esbuild'，需额外配置esbuildOptions: { treeShaking: false } - PostCSS 插件如
postcss-discard-unused必须从插件链中移除
变量体系最脆弱的地方不在定义，而在构建链路中被静默抹除——这点连很多资深前端都会忽略，直到上线后主题突然失效才去翻压缩日志。
