html暗黑模式仅响应系统主题而不改变它，核心依赖prefers-color-scheme（只读快照）与data-theme（用户权威主题源），需正确监听change、同步meta、localstorage及css变量兜底。
HTML暗黑模式不能改善系统主题，它只响应、不改变——网页无法控制操作系统或浏览器的深色/浅色设置，只能读取（prefers-color-scheme）或覆盖（data-theme）自己的样式表现。
prefers-color-scheme 是只读的“快照”，不是双向通道
这个 CSS 媒体查询只反映当前系统设置的瞬时状态，比如 macOS 的“自动”模式在夜间触发 dark，Windows 10/11 的“自动”则通常返回手动设定值，而非真实时间逻辑。它不提供 API 修改系统偏好，也不监听运行时变化（除非配合 window.matchMedia().addEventListener("change", ...)）。
常见错误现象：
- 页面首次加载按系统变暗了，但用户后来在系统设置里切回亮色，网页没反应 → 忘了加 change 监听；
- 开发者工具里强制启用 dark 模式，但页面没变 → CSS 规则写在了 <style></style> 外或被更高优先级规则覆盖。
- 必须把
@media (prefers-color-scheme: dark) { ... }写在有效的 CSS 上下文中（<style></style>或外链 CSS），JS 无法直接读取它的布尔结果 - 它只在 CSS 层生效，不影响
localStorage、data-theme或<meta name="color-scheme"> - 测试时别只靠浏览器 DevTools 模拟——要真改系统设置，尤其注意 Windows 和 macOS 行为差异
data-theme 才是页面的“权威主题源”
用户点按钮切换暗黑模式，本质是覆盖系统偏好：用 document.documentElement.setAttribute("data-theme", "dark") 显式设值，并同步存入 localStorage。这个值才是后续所有样式、逻辑、甚至第三方组件（如 Element Plus）实际依赖的状态。
为什么不用 class="dark"？
- class 容易和框架类名（Tailwind、BEM）冲突；
- 在 Shadow DOM 或 scoped 样式中，class 选择器穿透性差；
- JS 判断主题时得写 el.classList.contains("dark")，不如 el.dataset.theme === "dark" 清晰。
-
data-theme必须在 DOM 加载完成前（DOMContentLoaded或更早）就设置好，否则出现白屏闪动 - 务必同时更新
<meta name="color-scheme" content="dark light">，否则地址栏、表单控件等浏览器 UI 元素仍保持原色 - 不要让
prefers-color-scheme和data-theme逻辑耦合——前者只用于首次加载兜底，后者才是用户真实意图
localStorage 存的是用户选择，不是系统状态
localStorage.getItem("theme") 返回的值，代表用户最后一次主动点击按钮的结果，与系统当前是否深色无关。如果用户从未点过按钮，这个值是 null，此时才该 fallback 到 matchMedia。
容易踩的坑：
- 读取 localStorage 后直接设 data-theme，却忘了同步更新 <meta name="color-scheme"> → 地址栏还是白的；
- 切换按钮只改了 class，没写 localStorage.setItem("theme", nextTheme) → 刷新后回到系统默认；
- 在多个标签页间不同步：A 标签页切了暗色，B 标签页仍是亮色 → 需监听 storage 事件并广播更新。
- 初始化逻辑顺序必须是：
localStorage→matchMedia→ 设data-theme+meta+localStorage - 手动切换时，不要重新查
matchMedia，直接翻转当前值（dark↔light） -
storage事件只在其他标签页触发，当前页需用自定义事件（如dispatchEvent(new Event("themechange"))）通知内部模块
最常被忽略的一点：CSS 变量必须有默认值，且定义在 :root 下；没有兜底值的话，data-theme 还没设完、CSS 变量就已求值，页面会短暂显示未定义颜色。这比闪屏更难调试——它不报错，只悄悄变灰。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
