必须将所有主题变量显式定义在:root[data-theme="dark"]中以确保全局覆盖和避免fallback失效，因浏览器CSS层叠单次解析，漏定义变量会回退至旧值；contenteditable需手动继承color/background及caret-color；切换须早于首屏渲染并操作document.documentElement.setAttribute。
直接在 :root 里声明变量就能全局生效，但只写变量名不等于主题能切——必须配合 data-theme 或 class 控制作用域、显式覆盖所有变量、且切换时机要早于首屏渲染。
为什么必须把变量全写死在 :root[data-theme="dark"] 里
浏览器解析 CSS 是单次层叠过程，var(--border-color) 的值取决于当前匹配到的最高优先级声明。如果只在 JS 里改 --border-color，而漏了 --shadow-color，后者就会 fallback 到上一个有效值（可能是 light 主题的旧值），导致边框消失或阴影不可见。
-
[data-theme="dark"] :root权重是 110，远高于普通 class（10），不会被第三方库的.dark冲突 - 哪怕某个变量在 dark 模式下和 light 值相同，也得显式写出，比如
--border-color: #374151，不写 = 留坑 - 所有主题变量必须用 HSL/RGB 而非 HEX，方便后续用
color-mix()动态调亮暗
contenteditable 元素为啥切主题后颜色不对
contenteditable 区域默认不继承 color 和 background，即使你写了 :root { --text-primary: #e0e0e0; }，编辑器里文字仍可能是黑底白字，光标也不随主题变。
- 必须给编辑器根容器显式设置：
color: var(--text-primary); background: var(--bg-editor); - 光标颜色靠
caret-color: var(--text-primary);单独控制，它不会自动随color变 - 若用 Tiptap/Quill，检查其内置 class 是否硬编码了颜色；得用
!important或更高权重选择器覆盖
JS 切换主题时最常踩的三个坑
用 document.documentElement.style.setProperty() 看似简单，但极易失效——不是变量没设对，而是触发机制错了。
立即学习“前端免费学习笔记（深入）”；
- 别在
DOMContentLoaded之后才设data-theme，否则首屏已按默认主题渲染完，出现 FOUC（闪屏） - 切换动作必须操作
document.documentElement.setAttribute('data-theme', 'dark')，而不是style.setProperty()，后者只改内联样式，无法激活[data-theme="dark"] :root规则 - localStorage 读取必须同步：页面加载瞬间就执行
document.documentElement.setAttribute()，不能等 React/Vue mount 后再处理
真正难的不是写几行 CSS，而是确保每个用到颜色的地方都提前替换成 var(--xxx)，包括伪元素、SVG fill、表单状态色、第三方组件内部样式——漏一处，主题就崩一块，而且很难定位。
