data-theme必须挂载到document.documentElement上，否则::before、fixed元素、SVG填色等无法响应；常见错误是设在body上导致选择器不匹配、样式错乱；SSR需在html标签写死，CSS须用html[data-theme="dark"]定义变量并带回退值，初始化逻辑应置于head内联脚本中。
主题切换模块不是加个按钮再改几行 CSS 就能稳住的，核心卡点在 data-theme 必须挂载到 document.documentElement，否则 ::before、fixed 元素、SVG 填色全不响应——这是 90% 的人第一次调试失败的根源。
data-theme 必须设在 document.documentElement 上
常见错误是写 document.body.setAttribute('data-theme', 'dark')，表面样式变了，但打开 DevTools 查看 <html> 标签，根本没这个属性；[data-theme="dark"] 选择器压根没匹配上。后果是：弹窗遮罩层颜色错乱、图标 SVG 不变色、滚动条 thumb 仍为浅色。
-
document.documentElement等价于:root，是 CSS 变量唯一可靠的全局作用域 - 设在
body或某个容器上，会导致子元素继承链断裂，伪元素和 SVG 因脱离根作用域而无法读取变量 - 服务端渲染（SSR）时可直接在 HTML 模板里写死：
<html data-theme="light">，避免首屏闪白
CSS 中必须用 html[data-theme="dark"] 而非 .dark
用 class="dark" 切换看似简单，但极易与 Tailwind 的 dark: 前缀、BEM 的 block--theme-dark、或第三方 UI 库的内置 dark 类冲突。更麻烦的是，.dark .button 这类嵌套规则权重高、难覆盖、且无法保证所有组件都命中。
- 正确写法是：
html[data-theme="dark"] { --bg: #121212; --text: #e0e0e0; }，漏掉html前缀会导致权重不足或被其他规则压制 - 不要写：
:root .theme-dark { --bg: #121212; }——这不是嵌套，而是两个独立选择器，变量根本不会生效 - 所有用到变量的属性必须显式调用：
background-color: var(--bg);、fill: var(--icon-fill);，漏写等于白定义
初始化必须在 <head> 内联脚本中完成
如果等 DOM 加载完再执行 JS 设置 data-theme，浏览器已按默认 CSS 渲染一次，必然闪屏。不能靠“隐藏内容等 JS 执行完再显示”这种反模式。
立即学习“前端免费学习笔记（深入）”；
- 把初始化逻辑写进
<head>里的内联<script>，立即读取：localStorage.getItem('theme')，无值则 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 同步更新
<meta name="color-scheme">，确保地址栏、系统级 UI（如 iOS Safari 工具栏）颜色一致 - 过渡动画必须提前声明：
html { transition: background-color 0.3s ease, color 0.3s ease; }，JS 改变量后浏览器才可能平滑过渡
所有变量必须带回退值 + 显式 transition
很多人只写 color: var(--text-color);，结果切换时文字瞬间变黑或消失——因为变量未定义时，var(--text-color) 返回空值，浏览器回退到默认 color: black，而深色背景上就是看不见。
- 务必写回退值：
color: var(--text-color, #333);，第二个参数是未定义时的兜底色 - transition 不能靠 JS 动态加 class 触发，必须在初始 CSS 里声明好要过渡的属性，比如：
border-color、background-color、fill - SVG 图标填色必须用
fill: var(--icon-fill);，不能只靠 class 控制，否则切换时 SVG 不会重绘
最常被忽略的一点：CSS 变量本身不会触发重排，但如果你在 JS 里缓存了 getComputedStyle(document.documentElement).getPropertyValue('--bg') 的结果并复用，主题切换后它永远不变——得实时读，或者用 storage 事件监听重置。
