主题切换失效的根源是data-theme值与CSS选择器不一致，必须严格匹配；CSS变量须定义在:root，通过setAttribute('data-theme', 'value')触发重计算，transition加在var()调用属性上，localStorage优先于prefers-color-scheme。
data-theme 值必须与 CSS 选择器完全一致
主题切换失效最常见的原因是 JS 设置的 data-theme 值和 CSS 中写的属性选择器对不上。比如 JS 执行了 document.documentElement.setAttribute('data-theme', 'dark')，但 CSS 里写的是 [data-theme="theme-dark"] —— 浏览器根本不会匹配，变量一个都不会重算。
必须严格保证两边字符串完全相同：
-
data-theme="dark"→ CSS 用[data-theme="dark"] -
data-theme="sepia"→ CSS 用[data-theme="sepia"] - 不要加前缀、空格、大小写混用（
"Dark"或"dark mode"都不行）
:root 是唯一可靠的变量作用域起点
CSS 变量必须定义在 :root，否则伪元素、fixed 定位元素、子组件内联样式可能拿不到值。写在 .container 或 body 里，等于只局部生效。
所有主题分支都得基于 :root 层级覆盖：
立即学习“前端免费学习笔记（深入）”；
- 默认值写在
:root { --bg-color: #fff; } - 暗色主题写成
[data-theme="dark"] { --bg-color: #121212; }，不是.theme-dark :root - 避免用
!important锁死变量，它会阻断后续 JS 更新
切换时不用 JS 改 style，靠属性触发重计算
别写 document.documentElement.style.setProperty('--bg-color', '#121212') —— 这只改当前元素的内联样式，不触发全局变量重计算，且无法被 CSS 选择器捕获。
正确做法只有一步：document.documentElement.setAttribute('data-theme', 'dark')。浏览器会自动重新解析所有 [data-theme="dark"] 规则下的变量，并应用到所有 var(--bg-color) 调用处。
注意：
- 必须用
setAttribute或dataset.theme，不能只改body或某个 div - 如果用了
dataset.theme = 'dark'，HTML 里就得是data-theme（自动转驼峰），不是data-theme-name - transition 要加在使用
var()的属性上，比如background-color: var(--bg-color); transition: background-color 0.2s;
localStorage 同步和 prefers-color-scheme 兜底要分清职责
系统偏好（prefers-color-scheme）只能用于首次加载时 fallback，不能当作切换开关。用户手动点按钮切到浅色，系统仍是 dark，页面就会卡住。
初始化逻辑必须按优先级走：
- 先读
localStorage.getItem('theme')，有值就直接设data-theme并同步 checkbox - 没值才查
window.matchMedia('(prefers-color-scheme: dark)').matches，设初始值并存入 localStorage - 监听系统变化时，只在用户未手动切换过的情况下才更新（用
let userInitiated = false标记）
真正容易被忽略的是：CSS 变量本身不“主动响应”，它只在属性被重新计算时才生效；而重计算的触发点，永远是 DOM 属性变更或选择器匹配变化——不是 JS 读取、不是媒体查询变更、更不是 localStorage 存了值。
