必须使用 :root 声明 CSS 变量，因其是唯一能保证全局继承、全元素可访问的声明位置；写在类选择器下会导致作用域受限、变量覆盖混乱或回退失效，且 :root 语义准确、优先级稳定、兼容 SSR 和多主题扩展。
直接用 :root 声明变量 + document.documentElement.dataset.theme 切换，是最稳、最易维护的路径。其他方式要么优先级难控，要么刷新闪屏，要么不兼容 SSR。
为什么必须把变量写在 :root 里
CSS 变量的作用域是“继承链”，只有挂到 :root（即 <html>）上，才能被全页面所有元素通过 var(--color-primary) 读取。如果写在 .theme-dark 这类 class 下，变量只在该选择器匹配的子树生效，组件里调用会 fallback 到初始值或 inherit，颜色就断了。
-
:root是唯一能保证全局可访问的声明位置 - 别在组件里重复声明同名变量，比如
.button { --color-primary: red; }—— 这会覆盖根变量，且无法被兄弟组件复用 - 所有主题变量（哪怕浅色模式下值相同）都得在
:root和[data-theme="dark"] :root中完整定义，否则未声明的变量一渲染就丢色
[data-theme="dark"] :root 覆盖比 .dark class 更可靠
用属性选择器 [data-theme="dark"] :root 替代 .dark :root，能避开 class 优先级打架和命名冲突问题。比如你业务里已有 .dark-mode-toggle，加个 .dark 类就可能误触样式。
-
[data-theme="dark"] :root的 CSS 权重固定为 110，比普通 class（10）高得多，不易被覆盖 - 支持多主题扩展：只要改
data-theme="amber"，就能无缝接入第三套配色，不用新增 class 名 - Safari 旧版本对嵌套
@media (prefers-color-scheme) .dark :root支持不稳定，但[data-theme] :root全系兼容
JS 切换时最容易踩的三个坑
不是“设了变量就完事”，以下任一疏漏都会导致主题不生效、闪白或回退：
立即学习“前端免费学习笔记（深入）”；
- 没在 HTML 模板或内联 script 中预设初始
data-theme—— 浏览器先按默认 CSS 渲染，JS 执行后再切，必然 FOUC。正确做法：<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script>放在<head>里 - 只调
dataset.theme = 'dark'却忘了localStorage.setItem('ui-theme', 'dark')—— 刷新后变回默认 - 用
style.setProperty()直接改--hue，但没在:root中预先声明该变量 —— 浏览器找不到定义，var(--hue)回退为transparent或继承值，整页背景/文字瞬间消失
暗色模式下真正要动的颜色远不止背景和文字
只改 --bg-base 和 --text-primary 是远远不够的。浏览器原生控件、滚动条、SVG 图标、表单焦点环、阴影深度、甚至 caret-color 都得响应变量。
-
scrollbar-color: var(--text-primary) var(--bg-base);必须显式设置，否则 Safari 滚动条在暗色下仍为亮色 -
input:focus { outline-color: var(--primary-color); }—— 否则焦点框颜色卡在旧主题 -
svg * { fill: var(--text-secondary); }—— SVG 内部元素不会自动继承 color，得手动绑定 - 所有
box-shadow值必须用var(--shadow-sm)等变量，不能写死rgba(0,0,0,0.1)，否则暗色下阴影发灰或不可见
真正麻烦的从来不是“怎么切”，而是“切完之后，有多少地方你以为它会跟着变，其实根本没动”。每次新增一个 UI 组件，第一件事不是写样式，是检查它用了哪些变量、是否在所有主题下都定义了 fallback 值。
