必须将所有主题变量定义在 :root 中，因为 CSS 变量依赖继承，:root 即 html 根元素，确保 var(--bg-color) 在任意层级（包括伪元素、SVG、contenteditable）正确取值；否则切换 class 或 JS 修改时继承链断裂、复用失败、setProperty 无效、fallback 失效。
为什么必须把所有主题变量定义在 :root 里
因为 CSS 变量靠继承传播，:root 等价于 html 元素，是整个文档树的根。只有挂在这里，var(--bg-color) 才能在任意层级（包括 ::before、svg、contenteditable 区域）正确取值。
常见错误现象：
- 变量写在
.theme-dark选择器里 → 切换 class 后，子元素读不到新值，继承链断了 - 变量只定义在
body或组件级选择器（如.card）→ 兄弟组件无法复用，JS 修改document.documentElement.style.setProperty()完全无效 - 没预先声明就调
setProperty→var(--bg-color)fallback 为transparent或继承色，页面瞬间“失色”
transition 为什么对 --theme-color 无效
transition: --theme-color 0.3s 这种写法浏览器直接忽略，不报错也不生效。CSS 的 transition 不支持变量名作为过渡属性。
真正生效的方式是：把变量用在某个支持过渡的原生属性上，再对该属性加 transition：
立即学习“前端免费学习笔记（深入）”；
- ✅ 正确：
background-color: var(--theme-bg); transition: background-color 0.3s ease; - ✅ 正确：
color: var(--theme-text); transition: color 0.2s; - ✅ 正确：
filter: brightness(var(--brightness)); transition: filter 0.3s;（filter支持插值） - ❌ 错误：
transition: --theme-bg 0.3s; - ❌ 错误：在
@keyframes里动画--theme-bg值 —— 不生效
切换主题时如何避免闪屏和抖动
用户点击按钮后页面白一下或布局跳动，通常不是 JS 写错了，而是初始化和渲染节奏没对齐。
- 必须在
里就设置document.documentElement.dataset.theme = localStorage.getItem('theme') || 'light'，否则首屏渲染完才切主题，必然 FOUC - 所有尺寸变量（
--spacing-sm、--border-radius、--font-size）必须在初始 CSS 中定义，不能只在.theme-dark里补 —— 否则切换时会触发 layout 抖动 -
contenteditable区域默认不继承color和background-color，需显式声明：.editor-content { color: var(--editor-text); background-color: var(--editor-bg); } - 切换后立刻调
getComputedStyle会强制同步布局 → 改用requestAnimationFrame延迟读取
JS 切换主题的最小可靠操作路径
别用 style.setProperty() 逐个设值，也别拼 cssText —— 容易覆盖已有内联样式，维护爆炸。
- 推荐用 class 切换：
document.documentElement.classList.toggle('theme-dark') - CSS 里对应写两组
:root块：:root { --bg: #fff; }和:root.theme-dark { --bg: #121212; } - localStorage 存的是主题标识（如
'dark'），不是整套变量值；靠 CSS 规则驱动，不是靠 JS 注入 - 切换按钮点击后，同步做三件事：改 class、设
dataset.theme、存localStorage.setItem('theme', 'dark') - 不要在伪元素（
::before）里同时用变量 +transition—— 部分浏览器渲染有延迟
:root 中声明，哪怕只是占位；var(--x, #000) 的 fallback 只在变量未定义时生效，但若变量根本没声明，fallback 也可能失效，尤其在 SSR 场景下。 
