必须先在 :root 中定义所有主题变量的默认值，再用 @media (prefers-color-scheme: dark) 覆盖，否则首次渲染时未声明的 CSS 变量会回退为 transparent 或继承值，导致内容不可见或样式断裂；同时需配合 data-theme 属性、内联 JS 初始化及 html { color-scheme: light dark } 声明，才能兼顾系统偏好、手动切换与跨浏览器兼容性。
必须先在 :root 里定义默认（浅色）变量，再用 @media (prefers-color-scheme: dark) 覆盖，否则深色模式下部分变量会 fallback 到初始值甚至透明，导致白底黑字或内容消失。
为什么不能只写 @media (prefers-color-scheme: dark) 就完事
浏览器加载 CSS 时，会先按默认样式渲染；如果 :root 里没声明 --bg-color，那哪怕媒体查询里写了，var(--bg-color) 在首次计算时也会回退为 transparent 或继承值——尤其是未被包裹的 <input>、<button></button>、<select></select> 等原生控件，极易出现“深色背景上显白字但边框还是浅灰”的断裂感。
常见错误写法：
@media (prefers-color-scheme: dark) {
:root {
--bg-color: #121212;
--text-color: #e0e0e0;
}
}
→ 缺少默认声明，首屏即失效。
立即学习“前端免费学习笔记（深入）”；
:root 默认块必须完整声明所有变量
所有会在主题中用到的变量，都得在顶层 :root 块里一次性定义，哪怕深色和浅色值暂时相同。漏一个，就断一个。
-
--bg-color、--text-color、--border-color、--shadow-sm、--icon-fill都要列全 - 值必须带单位（如
16px）、语义化（如--spacing-md而非--s2） - 避免非法命名：
--font size无效，--font-size-lg才合法
如何让 prefers-color-scheme 和手动切换不冲突
媒体查询只响应系统设置，无法保存用户选择。想支持「用户点开关切暗色 + 刷新不丢」，就得靠 data-theme 属性配合高优先级 CSS 规则，且必须比媒体查询更早生效。
正确顺序（权重从低到高）：
- 基础
:root→ 浅色兜底 -
@media (prefers-color-scheme: dark) :root→ 系统自动响应 -
[data-theme="dark"] :root→ 用户手动覆盖，权重 110，稳压媒体查询
JS 初始化必须在 <head> 内联执行：
<script>
document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';
</script>
否则 DOM 渲染完成前无主题类，必然闪屏。
别忘了 html { color-scheme: light dark; }
这个声明不是可选的。它告诉浏览器：本页支持明暗双色方案，原生控件（滚动条、表单焦点环、<input type="range"> 滑块等）才能自动适配。没有它，哪怕 CSS 变量全对，滚动条还是亮色。
另外，prefers-color-scheme 在 Safari 旧版（≤13.1）中对 .dark :root 支持不稳定，但 [data-theme="dark"] :root 全系兼容——这点容易被忽略，尤其做跨端产品时。
