必须将CSS变量声明在:root下，否则主题切换无效；正确做法是用html[data-theme="dark"]覆盖:root变量，配合localStorage预设和classList.toggle实现无闪切换。
变量必须声明在 :root，否则切换无效
很多人把主题变量写在 .theme-dark 里，比如 :root .theme-dark { --bg: #111; } —— 这根本不会生效。浏览器解析时把它当作两个独立选择器，:root 和 .theme-dark 并不构成嵌套关系，变量压根没挂到根作用域上。
正确做法是分开定义：
:root {
--bg-primary: #ffffff;
--text-primary: #333333;
}
.theme-dark {
--bg-primary: #121212;
--text-primary: #f9fafb;
}
只要给 <html> 加上 class="theme-dark"，所有 var(--bg-primary) 就会自动取新值。关键点在于：:root 是唯一能保证变量全局可读的挂载点；body 或组件级声明，在 Shadow DOM、Vue 或 React 中可能透传失败。
用 classList.toggle() 切换 class，别碰 style.setProperty()
直接操作 document.documentElement.classList.toggle('theme-dark') 是最轻量、最稳定的方式。它只改一个 class，CSS 层叠自动响应，不需要手动遍历元素或反复 setProperty。
立即学习“前端免费学习笔记（深入）”；
- 避免用
document.documentElement.style.cssText = ''—— 会清空所有内联样式，包括框架注入的 class 或其他 JS 设置的样式 - 避免在 JS 里缓存
getComputedStyle().getPropertyValue()的结果，主题变了它也不会更新 - 如果用了 CSS-in-JS 库（如 Emotion），注意它可能绕过原生变量机制，优先走自己的主题上下文
localStorage 必须在 DOM 构建前读取并设置
浏览器先按默认主题渲染一次，JS 再改 class，中间就会闪一下。这不是动画问题，是渲染时机错位。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
解决方法：把初始化脚本放在 <head> 里，用内联 <script> 执行：
const savedTheme = localStorage.getItem('theme') || 'light';
document.documentElement.setAttribute('data-theme', savedTheme);
// 注意：这里用 data-theme 而不是 class，更稳妥（见下一条）
别等 DOMContentLoaded，那时重绘已完成；也别放 </body> 底部，太晚。
推荐用 html[data-theme="dark"] 而非 .theme-dark
.theme-dark 作为普通类选择器，无法直接覆盖 :root 中同名变量——因为它的权重不够，且语义模糊。而 html[data-theme="dark"] 是合法、高权重、无冲突的选择器，能直接作用于根节点。
更重要的是：
- 第三方库常操作
body.className，data-theme完全避开冲突 - 服务端渲染时可直接写死
<html data-theme="dark">，首屏不闪 - 配合
<meta name="color-scheme" content="dark">同步更新，Chrome 地址栏、Safari 表单控件才能真正变色
真正麻烦的不是写几行 toggle，而是变量作用域层级、JS 缓存行为、CSS 选择器权重之间那点微妙的冲突——调不通的时候，先打开开发者工具的 computed styles 面板，看变量最终值是从哪条规则来的。
