直接改:root变量值会失效，是因为style.setProperty设置的内联样式无法覆盖:root伪类声明，变量层叠优先级由CSS规则位置决定；必须通过data-theme属性切换选择器作用域，触发浏览器重算CSSOM。
为什么直接改 :root 变量值会失效
很多人写完 :root { --bg: #fff; }，再用 JS 执行 document.documentElement.style.setProperty('--bg', '#121212')，发现页面没变——根本原因是：CSS 变量的层叠优先级由声明位置决定，运行时通过 style.setProperty 设置的值属于内联样式，只对当前元素生效，而 :root 是伪类，不接受内联覆盖。更关键的是，子元素继承的是计算后的值，不是“可被 JS 覆盖的变量源”。
真正起效的方式是切换作用域：用 [data-theme="dark"] 这类选择器重新定义变量，让浏览器重算整个 CSSOM。
- 不要用
element.style.setProperty直接改:root变量 - 必须通过
document.documentElement.setAttribute('data-theme', 'dark')触发选择器匹配 -
[data-theme="dark"]块里的变量声明，要和:root中同名，否则var(--bg)会 fallback 到初始值甚至透明 - 确保
[data-theme="dark"]规则写在:root之后，否则层叠顺序导致覆盖失败
@media (prefers-color-scheme: dark) 和 data-theme 能不能共存
能，而且必须共存。媒体查询只响应系统设置，用户手动点击切换按钮时它完全不触发；data-theme 则负责用户主动选择。两者互不干扰，但需分层设计，否则会互相屏蔽。
- 在
:root中定义默认（亮色）变量值 - 用
@media (prefers-color-scheme: dark)覆盖同一组变量，作为系统偏好兜底 - 再单独写
html[data-theme="dark"]块，也覆盖同一组变量，作为用户手动控制入口 - 初始化时先读
localStorage.getItem('theme')，有值就设data-theme；没值才走matchMedia检测系统偏好 - 切记：不要在
[data-theme="dark"]里再嵌套@media，那会导致逻辑混乱且 Safari 兼容性差
颜色变量怎么命名才不容易翻车
硬编码 --dark-bg、--light-text 这类带模式前缀的变量，等于把主题耦合进命名里，后续加第三种主题（比如 sepia）就全得重命名。语义化才是可持续的关键。
立即学习“前端免费学习笔记（深入）”；
- 用功能或层级命名，例如
--bg-surface、--text-primary、--border-subtle - 所有变量统一放在
:root，别分散到组件内部（如.card { --bg: #fff; }），否则无法全局替换 - 每个
var()调用都带 fallback，例如background-color: var(--bg-surface, #fff);，避免变量未定义时渲染异常 - 深色模式下某些颜色不能简单取反，比如
--text-primary在暗色中应是#e0e0e0而非#000000，对比度要满足 WCAG AA 标准
切换时闪一下（FOUC）是怎么回事
闪屏本质是 CSS 加载和 DOM 渲染的时序问题：HTML 先渲染出亮色内容，等 CSS 解析完、JS 执行完、data-theme 补上，才重绘为暗色。纯 CSS 方案（仅靠 @media）无此问题，但一旦引入 JS 控制，就必须前置处理。
- 在
标签上直接写初始data-theme，比如服务端渲染时注入，或前端用内联 script 在就执行 - 避免把主题判断逻辑放在
window.onload或 React useEffect 里，太晚了 - 给
body加transition: background-color 0.3s, color 0.3s，但注意：CSS 变量本身不支持 transition，必须作用于实际属性 -
html { color-scheme: light dark; }必须加上，否则滚动条、input 边框等原生控件不会随主题变色，造成视觉割裂
var(--x, #000) 里后，它不会随主题动态更新。所以所有颜色变量必须明确定义在 :root 或对应主题选择器中，不能依赖 fallback 做主题分支。 
