必须将主题变量声明在 :root 中，因为 css 变量依赖继承链传播，:root 是唯一挂载到 根节点且全页面可读的位置；写在其他选择器内会导致作用域受限、变量断色、闪屏或颜色丢失。
必须把主题变量写在 :root 里，否则切换会失效、闪屏或颜色丢失。
为什么只能用 :root 声明主题变量
CSS 变量靠继承链传播，:root 是唯一能挂载到 根节点且全页面可读的位置。写在 .dark 或组件类里，变量只在该选择器作用域内生效，子元素调用 var(--color-primary) 时 fallback 到初始值或 inherit，直接断色。
常见错误现象：
-
.theme-dark { --bg-color: #1a1a1a; }—— 页面其他区域仍用默认背景 - 多个组件各自声明同名变量，互相覆盖，兄弟组件样式不一致
- 服务端渲染（SSR）下变量未提前注入，首屏渲染后 JS 才生效，出现 FOUC（白屏闪动）
[data-theme="dark"] :root 比 .dark :root 更可靠
用属性选择器而非 class 选择器覆盖变量，能避开优先级冲突和命名污染。比如业务中已有 .dark-mode-toggle，加个 .dark 类可能误触样式。
关键差异：
-
[data-theme="dark"] :root权重固定为 110，远高于普通 class（10） - 支持多主题扩展：
data-theme="amber"直接启用第三套配色，不用改 CSS 类名 - Safari 旧版对
@media (prefers-color-scheme) .dark :root支持不稳定，但[data-theme]全系兼容
正确写法示例：
:root {
--bg-color: #fff;
--text-color: #333;
}
[data-theme="dark"] :root {
--bg-color: #1e1e1e;
--text-color: #eee;
}
JS 切换时最容易漏掉的三件事
不是设了 dataset.theme 就完事——以下任一疏漏都会导致主题不生效：
- 没在
内联 script 中预设初始值：<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script>，否则浏览器先按无主题渲染，再 JS 补切，必然闪屏 - 只改
dataset.theme = 'dark'却忘了同步存localStorage.setItem('ui-theme', 'dark')，刷新后回退到默认 - 用
style.setProperty('--hue', '240')动态改变量，但:root里根本没声明--hue—— 浏览器找不到定义，var(--hue)回退为transparent或继承值，整页变空
暗色模式要动的不只是背景和文字
真正影响体验的是边界、阴影、表单控件、图标颜色、disabled 状态、甚至 SVG fill —— 这些都得在 :root 和 [data-theme="dark"] :root 里成套定义。漏掉一个，比如 --border-color 没覆盖，暗色下边框就还是浅灰，视觉断裂感极强。
容易被忽略的点：
- 所有主题变量（哪怕浅色/暗色值相同）都得完整声明，否则未声明变量一渲染就丢色
- 微信小程序里根元素是
page，得用page替代:root - 动画过渡需单独加
transition: background-color 0.2s, color 0.2s，CSS 变量本身不触发 transition
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
