纯CSS无法实现一键切换，必须用JS控制data-theme属性，CSS变量配合媒体查询实现主题切换；优先级为data-theme>prefers-color-scheme>默认:root；transition需加在body等渲染盒上，且仅对部分属性生效。
纯 CSS 无法实现“一键切换”——必须配合 JavaScript 控制状态，但样式逻辑可以完全交给 CSS 变量 + 媒体查询。 用户点击按钮时，JS 只负责切 data-theme 属性或 class，所有颜色、背景、边框等视觉变化都由 CSS 自动响应，这才是可维护的实战做法。
为什么不能只靠 @media (prefers-color-scheme: dark)？
它只响应系统设置，不响应用户主动点击。用户开了亮色系统，却想临时切暗色——@media 完全无效。更麻烦的是：服务端渲染（SSR）或首屏直出时，@media 还没生效，页面会先闪一次亮色，再变暗，体验断裂。真实项目里，必须让 JS 拿回控制权，CSS 只管“怎么画”，不管“什么时候画”。
data-theme 和 class 选哪个？
优先用 data-theme="dark" 放在 <html> 上，而不是 body.dark-theme：
-
data-theme更语义化，避免和业务 class 冲突（比如你有个组件叫.dark-card） - 它天然支持 CSS 层级穿透：
html[data-theme="dark"] .btn能直接覆盖任意深度的按钮样式 - 方便后续扩展：
data-theme="auto"可回退到媒体查询逻辑，"light"/"dark"强制锁定 - localStorage 存的值可以直接映射到这个属性，无需额外解析
变量定义顺序和 fallback 是最大雷区
下面这种写法会导致文字突然消失：
立即学习“前端免费学习笔记（深入）”；
:root {
--text-color: #e0e0e0;
}
@media (prefers-color-scheme: dark) {
:root { --text-color: #121212; }
}
错在哪？默认就把暗色值写进 :root，系统是亮色时变量值却是深灰，文字和白背景叠一起就看不见了。正确顺序是：
- 第一步：在顶层
:root中定义亮色值（这是 fallback，必须存在） - 第二步：用
@media (prefers-color-scheme: dark)覆盖变量 —— 仅当系统是暗色时才生效 - 第三步：用
html[data-theme="dark"]再覆盖一次，优先级高于媒体查询，确保手动切换能压倒系统设置
三者共存时，CSS 优先级自然决定谁胜出：data-theme > @media > 默认 :root。这样既尊重系统偏好，又允许用户覆盖。
transition 加在哪才真正起作用？
加在 body 或具体元素上，别加在 :root 或 html 上 —— 它们不是渲染盒，加了等于没加。而且只对部分属性过渡有效：
- ✅ 有效：
background-color、color、border-color、box-shadow - ❌ 无效：
filter、opacity（需单独声明transition: filter 0.3s）、display（不能过渡） - ⚠️ 注意：如果用了
var(--bg-color)，但--bg-color是个 CSS 变量，浏览器默认不会过渡变量本身，而是过渡使用该变量的属性（如background-color），所以 transition 必须写在用到var()的那个选择器上
最简实践就是：body { transition: background-color 0.3s, color 0.3s; }，稳且够用。
真正难的不是写几行 CSS，而是把颜色全部收口到变量里——一旦某个组件还写着 color: #333，它就会在暗色下永远黑着不动。变量方案看似多写两行，实则省掉未来三天的排查时间。
