必须将CSS变量声明在:root下以确保全局作用域，主题切换需结合class切换触发重绘、localStorage持久化用户偏好，并避免JS缓存变量值导致不响应。
直接用 CSS 自定义属性（--color-primary 这类）做主题切换，根本不需要 JS 框架或重载页面——但很多人卡在变量作用域和更新时机上，导致切了没反应、深色模式回退失效、或者组件样式不联动。
为什么 :root 里声明的变量切不了主题？
CSS 变量本身是静态的，写死在 :root 里就只有一份值；要切换，必须让浏览器“重新计算”这些变量。常见错误是只改 JS 里的 document.documentElement.style.setProperty()，却忘了变量可能被子元素内联覆盖，或被更具体的选择器锁死。
- 确保所有主题相关变量都定义在
:root，不要分散在组件级.card { --bg: #fff; }里 - 避免用
!important锁定变量值，它会阻断后续 JS 动态更新 - 如果用了 CSS-in-JS 库（如 Emotion），注意它可能绕过原生变量机制，优先走自己的主题上下文
prefers-color-scheme 和手动切换怎么共存？
用户系统设了深色模式，但又点按钮切回浅色——这时候不能只监听媒体查询，得用一个统一状态源（比如 localStorage + class 切换）来覆盖系统偏好。
anything-to-html
下载
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 初始化时先读
localStorage.getItem('theme')，有值就用它；否则再 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 给
html元素加class="theme-dark"或class="theme-light"，而不是只靠:root变量，方便写 CSS 回退逻辑 - 媒体查询监听器只负责“同步系统变更”，不负责“触发切换”：它该做的事是把新系统偏好写进 localStorage，再调用一次主题设置函数
如何让 React/Vue 组件响应主题变化？
纯 CSS 变量能自动重绘，但如果你在 JS 里读取了 getComputedStyle(document.documentElement).getPropertyValue('--color-bg') 并缓存结果，那主题变了它也不会更新——这是最隐蔽的坑。
立即学习“前端免费学习笔记（深入）”；
- React 中避免在
useEffect里一次性读取变量值做状态初始化；改用useCallback包裹一个实时读取函数，需要时再调用 - Vue 3 的
computed如果依赖了getComputedStyle，要手动监听storage事件或用watch监听 class 变化 - 更稳妥的做法：把主题当作一个 context/provider 状态管理，CSS 变量只是它的视觉输出层，JS 逻辑走统一状态
真正麻烦的不是写几行 setProperty，而是变量作用域层级、JS 缓存行为、以及 CSS 选择器权重之间那点微妙的冲突——调不通的时候，先查 computed styles 面板里变量最终值是多少，再看它是从哪条规则来的。
