:root 是唯一可靠位置，因其为文档根节点，确保所有后代（含伪元素、Shadow DOM、第三方组件）可读取变量；必须设回退值防失色；主题切换应批量更新或用 data-theme class 避免 FOUC 和性能问题。
直接在 :root 里定义语义化 CSS 变量（如 --color-primary），并确保所有样式都用 var(--color-primary) 引用，才能真正实现“改一处、全站变”。否则只是看起来像统一了，实际漏控、失效、闪屏全来。
为什么 :root 是唯一可靠的位置
CSS 变量作用域基于继承，:root 等价于 html 元素，是整个文档树的根节点。只有写在这里，所有后代元素（包括伪元素、Shadow DOM 子树、第三方组件内部）才可能读取到——前提是它们没被更近的作用域覆盖。
- 写在
.theme-dark类里？那只有该类后代能继承，button::before这种伪元素可能拿不到 - 写在
body或某个 wrapper 上？子组件一旦用了all: unset或inherit重置，变量就断了 - 用
@media直接覆盖变量？可以，但仅限系统偏好兜底；用户手动切换必须靠 JS 或 class 控制，不能只依赖它
var() 必须带回退值，否则页面会“失色”
浏览器遇到未定义的 var(--color-bg) 时，不会报错，而是直接 fallback 到 inherited 值或 transparent，导致文字消失、背景变白或按钮不可见。
- 正确写法：
background-color: var(--color-bg, #ffffff); - 错误写法：
background-color: var(--color-bg);（无回退，风险极高） - 回退值别偷懒写
inherit——它可能继承到transparent，尤其在表单控件或 SVG 中 - 所有用到变量的地方都要加：包括
border-color、fill、box-shadow、outline
主题切换时，别用 setProperty 逐个调用
连续调用十次 document.documentElement.style.setProperty('--x', 'y') 会触发多次重排，造成卡顿或视觉抖动。批量更新必须合并。
立即学习“前端免费学习笔记（深入）”；
- 推荐做法：构造一个对象，一次性注入到
style.cssText：document.documentElement.style.cssText += `--color-primary: #1890ff; --color-bg: #ffffff;`; - 更稳妥方案：用
data-themeclass 切换，把变量值全部收口在 CSS 规则块里，JS 只负责切 class - 注意权重：如果同时存在
:root.theme-dark和:root[data-theme="dark"]，后者优先级更高，但别混用，选一种坚持到底 - 切之前先存 localStorage，DOM 加载完立刻读取并设 class，避免 FOUC
最难的不是语法怎么写，而是让每个新写的组件、每行新补的样式、每个引入的第三方图标库，都默认走这套变量体系——漏掉一个 fill="#3b82f6"，主题切换就破功一次。
