必须将 data-theme 设在 html 元素上，因为 :root 对应 html，只有此处设置才能使 CSS 变量被所有层级（含伪元素、fixed 元素、SVG fill）继承；设在 body 会导致样式错乱与第三方组件失效。
直接用 data-theme + CSS 变量就能实现真正可控、可扩展、无闪动的多主题切换，不需要框架、不依赖 dark: 前缀，也不该把变量挂到 body 上。
为什么必须把 data-theme 设在 html 元素上
因为 :root 对应的就是 html 元素，只有改它，CSS 变量定义才能被所有层级（包括 ::before、fixed 定位元素、SVG fill）继承。设在 body 或某个容器上会导致：
-
document.body.setAttribute('data-theme', 'dark')根本不匹配[data-theme="dark"] :root选择器 - 顶部导航栏、弹出层、滚动条颜色错乱
- 第三方组件（如 Headless UI）的伪元素无法响应主题
如何写 CSS 才能让 bg-[var(--color-bg)] 真正生效
Tailwind 默认会忽略任意 var() 值，不是语法错误，是构建时静态分析失败。必须显式告诉它哪些值允许出现：
- 在
tailwind.config.js的safelist中加入：['bg-[var(--color-bg)]', 'text-[var(--color-text)]'] - 或更宽松但实用：
[/^bg-\[.*\]$/, /^text-\[.*\]$/] -
bg-[var(--color-bg)]中的括号必须是英文半角，且var(--color-bg)不能带空格，否则编译报错Invalid arbitrary value - VS Code 插件可能标红，但只要配置了
safelist，构建就通过
切换主题时怎么避免白屏或颜色跳变
闪动本质是浏览器先按默认样式渲染，再等 JS 执行完才重绘。关键在“时机”和“完整性”：
立即学习“前端免费学习笔记（深入）”；
- 必须在
内放内联脚本：<script>document.documentElement.dataset.theme = localStorage.getItem('theme') || 'light';</script> - 不能等到
DOMContentLoaded或封装成函数再执行——太晚了 - 每次切换后，必须同步调用：
localStorage.setItem('theme', 'dark')，否则刷新即失效 - 所有主题块都要完整声明变量，比如
[data-theme="dark"]里不能只写--color-bg，还要有--color-border、--shadow-sm、--icon-fill，否则那些属性会 fallback 到初始值或透明
怎么让系统偏好和手动切换共存而不冲突
prefers-color-scheme 是只读信号，只能用作首次加载的 fallback，不能当控制源：
- 页面加载时：先读
localStorage.getItem('theme')，有值则直接设；没值才查window.matchMedia('(prefers-color-scheme: dark)').matches - 监听系统变化仅用于更新 localStorage，不直接触发主题切换：
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', e => { if (!localStorage.getItem('theme')) localStorage.setItem('theme', e.matches ? 'dark' : 'light'); }) - 永远以
data-theme为唯一可信状态，JS 只操作它，CSS 只响应它
最容易被忽略的是：变量名必须语义化（如 --color-bg-primary），不能带主题倾向（如 --dark-bg）；还有 SVG 的 fill、滚动条、表单控件边框这些非背景/文字类属性，90% 的人第一次都会漏掉它们的变量映射。
