暗黑模式切换必须用@media(prefs-color-scheme:dark)独立声明:root变量，不可嵌套伪类；手动切换需[data-theme="dark"]:root覆盖全部变量，且JS初始化须在head内联执行。
不能用伪类优化暗黑模式切换——:root 不是伪类，@media (prefers-color-scheme: dark) 也不是伪类，它们根本不能“嵌套”或“配合伪类”来优化。 所有把 :root 当作伪类、或试图写 .dark :root:hover 这类规则的，浏览器直接忽略整块 CSS。
为什么 :root 不是伪类？
:root 是一个伪类选择器，但它只匹配文档根元素（即 ），作用是提供全局变量挂载点。它本身不响应交互、不随状态变化、也不支持嵌套媒体查询。真正驱动暗黑模式的是媒体查询，不是伪类逻辑。
-
:root必须单独存在，且所有主题变量必须在顶层:root块中完整声明，否则首次渲染就 fallback 到transparent或初始值 - 写成
.dark :root或body:root是无效语法，浏览器解析失败 - 伪类如
:hover、:focus无法触发主题切换，它们只影响单个元素状态，不改变全局变量继承链
@media (prefers-color-scheme: dark) 必须独立顶层书写
这个媒体查询不是选择器，不能出现在任何大括号内部，也不能和 class 或属性选择器混写。浏览器只认这种格式：
:root {
--bg-primary: #fff;
--text-primary: #333;
}
@media (prefers-color-scheme: dark) {
:root {
--bg-primary: #1e1e2e;
--text-primary: #e6e6e6;
}
}
- 写成
.theme-dark @media (...) { }或html[data-theme="dark"] @media (...) { }—— 整块被忽略 - 必须放在 CSS 文件靠前位置，早于所有依赖这些变量的样式规则，否则变量未定义导致闪屏或断色
- Safari ≤16.4 和部分 Android WebView 不响应运行时系统主题切换，页面不会重绘，必须刷新
[data-theme="dark"] :root 才是手动切换的正确写法
当用户点击按钮主动切主题时，@media 失效，必须靠属性选择器覆盖 :root 变量。关键点在于选择器权重和作用域隔离：
立即学习“前端免费学习笔记（深入）”；
-
[data-theme="dark"] :root权重为 110，高于普通 class（10），能稳定压过默认定义 - 不能只写
[data-theme="dark"]然后在里面设变量——那些变量不会被input、button、伪元素等继承，因为它们不在该选择器路径下 - 必须补全所有变量：哪怕暗色模式下
--border-color和亮色一样，也要在[data-theme="dark"] :root中显式写出，否则首次渲染时 fallback - JS 初始化必须在
内联脚本中完成：document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';，否则 FOUC 不可避免
color-scheme 属性只影响原生控件，不能替代样式
color-scheme: light dark 是一个提示，不是样式指令。它只对 或 :root 设置才生效，且仅作用于：
-
<input type="range">、<select></select>、复选框、单选按钮、滚动条 - 不会改
<input>背景、<textarea></textarea>边框、SVGfill或自定义组件 - Chrome 85+、Firefox 96+、Safari 13.1+ 支持；老版本直接忽略
- 即使加了
color-scheme，仍需手动写input { background: #1e1e2e; color: #e6e6e6; }
最易被忽略的其实是变量声明完整性——漏掉一个 --shadow-sm 或 --icon-color，暗色下对应区域就会透明、错位或不可见，而这类问题在开发阶段往往因缓存或局部预览被掩盖，上线后才集中爆发。
