CSS变量必须声明在:root中才能全局继承，错误地写在其他选择器内会导致子元素、伪元素、SVG等无法获取；需确保变量名正确、大小写敏感、作用域完整，并同步localStorage与初始渲染。
所有主题变量必须声明在 :root 里
浏览器只从 :root（即 html 元素）继承 CSS 变量，写在 body、.theme-dark 或任意组件选择器里，子元素都取不到。常见错误是把暗色变量塞进 [data-theme="dark"] 里却忘了包裹 :root ——结果只有直接匹配该选择器的元素生效，伪元素、fixed 定位弹窗、SVG fill 全部失效。
正确写法是：
:root {
--color-primary: #42b983;
--color-bg: #fff;
}
[data-theme="dark"] :root {
--color-primary: #5ccf99;
--color-bg: #1e1e1e;
}
注意：[data-theme="dark"] :root 权重为 110，远高于普通 class（10），能稳压业务样式；而 :root.dark 在复杂项目中容易被第三方组件样式意外覆盖。
var(--x) 没变色？先查「计算样式」里是否展开
浏览器对未定义或拼错的 var(--x) 不报错，只静默 fallback 到继承值或默认值（比如文字突然变透明）。打开开发者工具 → 选中元素 → 看「计算样式」面板：如果显示仍是 var(--text-color) 而没变成 #333，说明变量根本没声明，或作用域断了。
立即学习“前端免费学习笔记（深入）”；
-
--text-color必须带双短横，写成text-color或-text-color会被完全忽略 - 大小写敏感：
--TextColor≠--text-color - 漏掉
:root声明位置，比如只写在.card里，那.button就取不到
第三方组件和伪元素必须手动接入变量
CSS 变量不会自动渗透进已编译好的第三方 UI 库（如 Ant Design、Element Plus）或内联样式。它们内部若没用 var()，你改了 :root 也白搭。
关键补漏点：
-
::before/::after里的background-color、color、border-color都得显式写成var(--x) - SVG 的
fill和stroke属性不继承 CSS 变量，必须手动设：fill: var(--icon-color) - 表单状态伪类（
input:focus、button:active）同样要逐个替换 - Tailwind 用户需在
tailwind.config.js的safelist加：['bg-[var(--color-bg)]', 'text-[var(--color-text)]']，否则 JIT 编译会跳过
切换主题时 localStorage 和初始渲染必须同步
页面闪白、刷新回退到浅色，几乎全是 JS 执行时机和持久化没对齐导致的。
- 不能等
DOMContentLoaded再设置：<script>document.documentElement.dataset.theme = localStorage.getItem('theme') || 'light';</script>必须放在<head>里内联执行 - 每次调用
setProperty()后，必须立刻localStorage.setItem('theme', 'dark')，否则刷新就丢状态 - 所有主题块要完整声明变量：比如
[data-theme="dark"] :root里不能只写--color-bg，还得有--color-border、--shadow-sm、--icon-fill，否则这些属性会 fallback 到初始值或透明
真正难的不是写几行 setProperty，而是确保每处颜色、边框、阴影、图标描边都已用变量接管，且没有 JS 硬编码或第三方库绕过链路——漏一处，主题就断一节。
