HTML暗黑模式与系统主题是两套独立机制，网页不会自动响应系统切换；需用window.matchMedia监听prefers-color-scheme变化，配合data-theme、CSS变量、localStorage及color-scheme meta标签实现协同。
HTML暗黑模式和系统主题不冲突，但也不会自动协同——它们是两套完全独立的机制，网页不会因为系统切了暗色就“自动变暗”，也不会因网页设了暗色而影响系统设置。
prefers-color-scheme 只是提示，不是指令
浏览器通过 window.matchMedia("(prefers-color-scheme: dark)") 获取的是用户在操作系统里表达的「偏好」，它既不保证实时同步，也不触发强制样式更新。这个媒体查询返回的 matches 值只在 JS 执行那一刻有效，后续系统切换主题时，若没监听 change 事件，页面就完全无感。
- 首次加载时读一次
matches是必须的，但仅靠它无法响应运行时变化 - 监听必须写守卫：只有
!localStorage.getItem("theme")为真时才响应 change，否则用户手动选的主题会被悄悄覆盖 - 错误做法：每次刷新都先查系统偏好，再决定用哪个主题——这会导致用户刚点完“亮色”，刷新又回暗色
data-theme 必须在 DOM 渲染前设置
如果 JS 在 DOMContentLoaded 之后才给 document.documentElement 设置 data-theme，浏览器会先按无主题 CSS 渲染一遍（通常是亮色），再重绘，造成闪屏。这不是视觉瑕疵，而是逻辑断裂。
- 解决方案：把初始化逻辑写在
<script>标签里，并放在<head>底部，确保早于 CSS 解析完成 - 兼容性注意：Safari 旧版对
dataset.theme支持不稳定，建议统一用setAttribute("data-theme", value) -
<meta name="color-scheme" content="light dark">必须存在，否则原生控件（如<input>、滚动条）颜色不会随主题变化
CSS 变量必须有默认值且定义在 :root
任何一处硬编码颜色，比如 style="background: #121212" 或 CSS 中直接写死 border: 1px solid #333，都会让整套主题系统失效——变量没被引用，切换就等于没发生。
立即学习“前端免费学习笔记（深入）”；
- 所有颜色、边框、阴影、文字色都得走
var(--bg)、var(--border)这类变量 -
:root下必须提供默认值，例如--bg: #ffffff，否则未匹配data-theme时页面直接白屏或不可读 - 不要用 class 切换主题（如
class="dark"），容易和语言 class、第三方组件 class 冲突；data-theme是更干净、语义更明确的选择
最常被跳过的环节是：没在 JS 初始化阶段同步 localStorage 和 data-theme，也没在 change 回调里同时更新两者。结果就是系统变了、页面没变，或者用户点了切换、下次打开又还原——这些都不是 bug，是主题控制权没理清。
