深色模式切换失败主因是CSS变量作用域和优先级错误：必须在:root声明基础变量，.dark仅用于覆盖；class切换需确保操作document.documentElement且名称匹配；iframe或shadow DOM需同步设置变量；还需配对更新所有相关样式属性。
深色模式切换失败，:root 变量没生效？检查作用域和优先级
CSS Variable（自定义属性）必须在 :root 或目标元素上声明才能被继承或使用；如果只在某个 .dark 类里定义变量，但未在根节点设置初始值，color: var(--text-color) 会回退到默认值甚至失效。常见错误是把所有变量写在 .dark 里，却忘了 :root 中的默认浅色定义。
-
:root中定义所有基础变量（如--bg-color、--text-color），确保页面加载时有可用值 -
.dark类仅用于覆盖（:root.dark { --bg-color: #1e1e1e; }），不要删掉:root原始声明 - 避免用
!important覆盖变量——它对var()无效；变量本身不支持!important，只能靠选择器权重或声明顺序控制
切换按钮点击后界面不动？document.documentElement.classList.toggle() 没触发重绘
单纯切换 class 不会自动刷新 CSS 变量计算结果，但现代浏览器只要 DOM class 变了，就会重新解析样式表——问题往往出在 JS 执行时机或 class 名不匹配。
- 确认操作的是
document.documentElement（不是body），因为:root对应的就是html元素 - 检查 class 名是否和 CSS 中一致：比如 JS 切换
dark，但 CSS 写的是.dark-mode，就完全不生效 - 首次加载时建议读取系统偏好：
if (window.matchMedia('(prefers-color-scheme: dark)').matches) document.documentElement.classList.add('dark')
编辑器内实时预览失真？iframe 或 shadow DOM 隔离了 :root 变量
很多 HTML 编辑器（如 CodePen、StackBlitz 或自建 iframe 预览）把用户代码渲染在独立上下文里，:root 是 iframe 自己的根，不是父页面的。此时你在主页面设 document.documentElement.classList，对 iframe 内样式毫无影响。
- 若用 iframe 预览，需把主题 class 同步写入 iframe 的
documentElement：iframe.contentDocument.documentElement.classList.toggle('dark', isDark) - 若编辑器用 shadow DOM 封装预览区，变量必须在 shadow root 的
:host或内部:root重复声明，无法跨 shadow boundary 继承 - 本地测试建议直接开一个 .html 文件跑，绕过编辑器沙箱干扰
字体发虚、按钮边框消失？深色模式下 color 和 background 没配对更新
CSS Variable 本身不保证语义正确——你设了 --bg-color: #000，但忘了同步改 --border-color: #333，或者 --text-color 在深色背景上对比度不足，就会出现视觉异常。这不是变量机制的问题，而是变量使用逻辑疏漏。
立即学习“前端免费学习笔记（深入）”；
- 深色模式下务必检查所有用到
var(--xxx)的属性：背景、文字、边框、阴影、占位符、SVG fill 等 - 别只改颜色，注意
box-shadow的模糊半径在深色背景下可能更显眼，需调低或换色 - 输入框
::placeholder、禁用态:disabled、焦点 outline 都要单独适配，它们不会自动继承变量
var() 不会帮你做语义判断，只忠实地代入值。 
