:root是唯一可靠的作用域起点，因其等价于html根元素，确保所有后代元素可通过var()继承变量；写在.theme-dark等普通类中会导致作用域受限，contenteditable区域等深层组件无法读取，且破坏ssr一致性。
为什么 :root 是唯一可靠的作用域起点
直接在 .theme-dark 类里声明 --bg-color，子元素根本拿不到——CSS 变量作用域由选择器决定，.theme-dark 是普通类，不覆盖全局；只有 :root 等价于 html 元素，是整个文档的根级作用域，所有后代都能通过 var(--bg-color) 访问。
常见错误现象：切主题后按钮颜色变了，但编辑器内文字还是黑底白字。本质不是变量没设上，而是变量压根没挂到 :root 上，导致 contenteditable 区域无法继承。
-
:root声明确保 SSR 渲染时变量已就位，避免服务端与客户端样式不一致 - 写在
body或容器上的变量，会被inherit阻断，尤其影响富文本编辑器、代码块等嵌套深的组件 - 媒体查询中不能嵌套
:root（如@media (prefers-color-scheme: dark) { :root { ... } }是非法语法，浏览器直接忽略）
data-theme 比 class 更安全的切换方式
用 document.body.classList.toggle('theme-dark') 看似简单，但会引发三类问题：第三方库（如 Tiptap、Quill）可能自带 dark 类冲突；Tailwind 的 dark: 前缀规则会和你的 .theme-dark .button 嵌套规则打架；更麻烦的是，.theme-dark :root 这种写法实际是两个独立选择器，:root 不受 .theme-dark 影响，变量根本不会重写。
正确做法是操作 html 元素的 data-theme 属性：document.documentElement.setAttribute('data-theme', 'dark')，对应 CSS 写成 [data-theme="dark"] :root { --bg-color: #121212; }。
-
data-属性语义清晰，服务端可直出，首屏无闪 - 选择器权重足够高，能稳定覆盖默认
:root变量 - 避开所有框架 class 命名冲突，比如 Bootstrap 的
dark、Ant Design 的ant-dark
contenteditable 元素必须显式继承变量
CSS 变量本身不触发重绘，但 contenteditable 区域默认不继承 color 和 background，哪怕你写了 color: var(--text-primary); 在父容器上，编辑区文字仍可能保持浏览器默认色。
实操必须给编辑器根容器（如 <div contenteditable="true">）单独加声明：
<ul>
<li><code>color: var(--text-primary);
background: var(--bg-editor);caret-color: var(--text-primary); —— 光标颜色不会随 color 自动变，必须单独设!important 覆盖，或改用更高权重选择器（如 [data-theme="dark"] .ql-editor）变量回退值和过渡动画的硬性要求
没写回退值的 var(--text-color, #333)，一旦变量未定义（比如 localStorage 读取失败或 JS 加载异常），整个页面文字就消失；没提前写死 transition 的 body，切主题时背景会“啪”一下跳变，没有渐变效果。
- 所有
var()必须带回退值，尤其是color、background-color、border-color等关键视觉属性 -
transition必须写在 CSS 中（如body { transition: background-color 0.2s ease, color 0.2s ease; }），不能靠 JS 动态加，否则首次切换无动画 - 慎用变量驱动
font-size或padding—— 它们可能触发重排，造成卡顿，除非你明确需要响应式缩放
最易被忽略的点：localStorage 读取必须在 DOM 构建前完成。放在 DOMContentLoaded 里，用户会先看到默认主题闪一下再切过去。要把初始化脚本塞进 里的内联 <script></script>，顺序是读取 → 设 data-theme → 同步更新 <meta name="color-scheme">。
