如何使用CSS:root管理全局主题变量

必须用 :root 声明全局变量，因其特异性更高（0-1-0）、是规范定义的文档根作用域锚点，且在 SVG、Shadow DOM 和旧版 Safari 中稳定生效；html 或 body 声明属误用，前者不保证跨上下文兼容，后者变量无法向上继承。

必须用 :root 声明，其他位置（html、body、class）都不算真正全局，子元素大概率读不到或被覆盖。

为什么只能写 :root，不能写 html 或 body

虽然 :root 在 HTML 中等价于 html 元素，但它特异性更高（0-1-0 vs 0-0-1），且是 CSS 规范定义的“文档根作用域”锚点。写成 html { --color-primary: #007bff; } 看似能用，实则是误用——它只是普通选择器，不保证在 SVG、Shadow DOM、旧版 Safari（iOS 12.2 之前）中生效。body { --x: red; } 更糟：变量无法向上继承到 html 自身，连 head 里的样式或伪元素都可能读不到。

:root 里声明变量的硬性语法要求

1. 变量名必须以 -- 开头，比如 --text-color，写成 text-color 或 $primary 直接被忽略
2. 每个声明末尾必须加分号，包括最后一个：--size: 16px; ✅，--size: 16px ❌（后续所有变量声明静默失效）
3. 值必须是合法 CSS 值：颜色写 #007bff，尺寸带单位如 1rem，字符串加引号如 "Inter"
4. 不能在 :root 内部嵌套引用未声明变量，例如 --text: var(--primary); —— 部分旧版 Safari 会解析失败
5. 声明块必须出现在任何 var(--xxx) 使用之前，CSS 是顺序解析的

如何安全使用 var(--xxx) 防止静默失效

var() 不报错也不警告，变量未定义时属性直接“消失”，不是继承父级值，而是回退到 initial 或 inherit，导致文字看不见、背景透明等故障。

1. 每个 var() 必须带 fallback，例如 color: var(--text-primary, #333);，第二个参数只在变量拼错、未声明或 JS 设置失败时启用
2. fallback 值必须是该属性的合法值：font-size: var(--size, auto); ❌（auto 不是 font-size 的合法值）
3. 不要指望 fallback 实现主题切换，它只是兜底；深色模式该用 :root[data-theme="dark"] 覆盖整组变量
4. 避免在 @keyframes 中直接用 var() 控制动画值，部分浏览器不支持

主题切换时变量没更新？问题不在变量本身

改了 document.documentElement.style.setProperty('--bg-color', '#121212') 但样式没变，根本原因不是变量没生效，而是浏览器没触发重绘——CSS 变量是运行时求值的，但依赖它的属性（如 background-color）本身没“动”，浏览器不认为需要重算。

1. 最稳妥解法是绑定 class 切换：document.documentElement.dataset.theme = 'dark'，再用 :root[data-theme="dark"] 覆盖变量，靠选择器权重强制样式重解析
2. 不要用 .dark-mode :root 这种写法——:root 永远是顶层，不可能是某个 class 的后代
3. 第三方组件（如 Ant Design）常内联写死颜色，不响应你的变量，需检查 computed styles 确认最终值是否来自 var()
4. 所有主题下用到的变量，必须在默认 :root 块中完整声明，哪怕深色模式下值相同也不能漏，否则渲染即 fallback

真正容易被忽略的点是：变量声明位置和 fallback 的合法性。漏一个分号、少一个 --、fallback 值非法，都会导致静默失效，DevTools 里看不出错误，只看到样式“莫名消失”。