必须把所有主题变量声明在:root里，因为CSS变量依赖继承传播，而:root即<html>元素是整个文档继承链的根；写在其他选择器（如.theme-dark或body）下会导致变量作用域受限，子元素读取var(--bg)时可能失效而回退到默认值。
必须把所有主题变量声明在 :root 里，否则切换时部分元素颜色会丢失或 fallback 到默认值。
为什么 :root 是唯一安全的声明位置
CSS 变量靠继承传播，而 :root 就是 <html> 元素，是整个文档继承链的根。写在其他选择器（比如 .theme-dark 或 body）下，变量只在该选择器匹配的子树内生效，组件内部读取 var(--bg) 时可能拿不到值，直接回退到初始色或透明。
常见错误包括：
- 在
button { --primary: blue; }中定义变量——按钮自己能用，但兄弟组件、SVG、伪元素都读不到 - 用
.dark :root而非[data-theme="dark"] :root——class 名易冲突，且优先级不稳定 - 漏掉
--前缀，写成primary-color——浏览器完全忽略，无报错
:root 中该定义哪些变量
别贪多，5–8 个语义化变量足够覆盖绝大多数场景：比如 --color-primary、--color-text、--color-bg、--color-border、--color-success。多了反而难维护，也容易在 JS 切换时漏设。
立即学习“前端免费学习笔记（深入）”；
关键原则：
- 所有用到颜色的地方（
background-color、color、border-color、box-shadow、::before/::after的content和background、svg的fill/stroke）必须显式替换成var(--color-bg) - 避免
rgba(var(--color-primary), 0.1)这类写法——CSS 变量不能直接参与函数计算，得拆成rgba(var(--r), var(--g), var(--b), 0.1)或改用color-mix() - 深色模式的
--color-bg推荐用#121212而非纯黑#000，更护眼且对比度合理
JS 切换主题时最常踩的三个坑
不是调了 style.setProperty() 就完事。以下任一疏漏都会导致闪屏、颜色断层或刷新后失效：
- 没在
<head>里预设初始data-theme：<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script>必须放在 CSS 加载前，否则首屏先按默认样式渲染，JS 执行后再切，必然 FOUC - 只改
dataset.theme却忘了同步localStorage.setItem('ui-theme', 'dark')——刷新后变回默认 - 用
style.setProperty('--hue', '240')但:root里根本没声明--hue——浏览器找不到定义，var(--hue)回退为transparent或继承值，整页背景/文字瞬间消失
transition 对变量本身无效，必须作用于具体属性
写 transition: --color-primary 0.3s 完全没用，浏览器直接忽略，连 warning 都不报。真正生效的方式是：把变量用在支持过渡的属性上，再对那个属性加 transition。
例如：
body {
background-color: var(--color-bg);
color: var(--color-text);
transition: background-color, color 0.3s ease;
}
注意：
- 所有尺寸类变量（如
--spacing-sm、--radius-md）也得在初始 CSS 中定义好，否则切换时可能抖动 - 别对所有属性用
transition: all——性能差，且可能意外触发不期望的动画 - 第三方 UI 库（如 Ant Design）若未开启 CSS 变量支持，它们内部 class 不会响应你的
--color-primary，得查文档确认是否兼容
