必须将data-theme设在html元素上，因其确保CSS变量全局生效、伪元素精准命中、第三方库主题注入正确，并支持SSR直出避免闪屏；挂body会导致样式错乱与兼容问题。
必须用 data-theme 属性控制，不能只靠 @media (prefers-color-scheme: dark) —— 后者不响应手动切换，刷新即失效。
为什么 data-theme 必须挂在 html 元素上
挂 body 或其他元素会导致三类问题：CSS 伪元素（如 input::-webkit-inner-spin-button）无法命中；Tailwind/Bootstrap 等库的主题注入错乱；服务端渲染（SSR）时无法直出主题状态，首屏必闪白或闪黑。Safari 14–15 对嵌套媒体查询有已知 bug，但 html[data-theme="dark"] 选择器稳定可靠。
初始化 JS 必须写成：
document.documentElement.dataset.theme = "dark";
清空时用 delete document.documentElement.dataset.theme，别设成空字符串或 "light" —— [data-theme=""] 不会匹配空属性值。
立即学习“前端免费学习笔记（深入）”；
:root 变量定义与覆盖的写法陷阱
CSS 自定义属性不继承，但会级联；所有主题变量必须在 :root 层级定义，子选择器里重定义无效。
- 基础变量统一声明在
:root，例如--bg-primary、--text-secondary - 暗色覆盖必须用
html[data-theme="dark"] :root，不是html[data-theme="dark"]直接写变量 - 媒体查询仅作兜底，且要加
:root:not([data-theme="light"])避免与用户手动设置冲突
错误示例（变量不会生效）：
html[data-theme="dark"] {
--bg-primary: #121212;
}
正确写法：
:root {
--bg-primary: #ffffff;
--text-primary: #1a1a1a;
}
html[data-theme="dark"] :root {
--bg-primary: #121212;
--text-primary: #e0e0e0;
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--bg-primary: #121212;
--text-primary: #e0e0e0;
}
}
首次加载时避免闪屏的关键时机
页面先按默认亮色渲染、再切主题 = 闪白；等 DOMContentLoaded 才读取 localStorage = 太晚。必须在所有 CSS 加载前完成 data-theme 设置。
- 最佳做法：内联一段
<script>放在<head>最顶部、所有<link rel="stylesheet">之前 - 读取逻辑必须用
??（空值合并），不能用||—— 因为localStorage.getItem('theme')返回null或字符串，而空字符串会被||转为false - fallback 到系统偏好后，必须显式设值，不能留空 ——
data-theme属性不存在，CSS 规则完全不生效
标准初始化脚本：
const saved = localStorage.getItem('theme');
const systemPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
document.documentElement.dataset.theme = saved ?? (systemPrefersDark ? 'dark' : 'light');
切换按钮与系统偏好监听的边界
用户手动切换和系统偏好变化是两件事，处理逻辑不能混用。
- 按钮点击只改
data-theme和localStorage，不碰matchMedia - 监听
matchMedia('(prefers-color-scheme: dark)').addEventListener('change', ...)仅用于更新localStorage，不直接改data-theme—— 否则会覆盖用户主动选择 - 组件内所有颜色必须用
var(--bg-primary)，禁止硬编码#121212—— 一旦写死就绕过主题系统
容易被忽略的一点：过渡动画必须写在 body 或根元素上，且只对变量引用的属性生效（如 background-color、color），不能指望整个 html[data-theme="dark"] 切换有动画 —— 它本身不触发重绘，只是启用新变量集。
