必须把主题变量写在 :root 里，因为 CSS 变量依赖继承传播，:root 是唯一挂载到 <html> 根节点且全页面可读的位置；写在 .dark 或组件类中会导致作用域受限、断色、覆盖混乱、SSR 下 FOUC 等问题。
为什么必须把主题变量写在 :root 里
因为 CSS 变量靠继承链传播，:root 是唯一能挂载到 <html> 根节点且全页面可读的位置。写在 .dark 或组件类里，变量只在该选择器作用域内生效，子元素调用 var(--color-primary) 时 fallback 到初始值或 inherit，直接断色。
常见错误现象：
-
.theme-dark { --bg-color: #1a1a1a; }—— 页面其他区域仍用默认背景 - 多个组件各自声明同名变量，互相覆盖，兄弟组件样式不一致
- 服务端渲染（SSR）下变量未提前注入，首屏渲染后 JS 才生效，出现 FOUC（白屏闪动）
[data-theme="dark"] :root 比 .dark :root 更可靠
用属性选择器而非 class 选择器覆盖变量，能避开优先级冲突和命名污染。比如业务中已有 .dark-mode-toggle，加个 .dark 类可能误触样式。
关键差异：
立即学习“前端免费学习笔记（深入）”；
-
[data-theme="dark"] :root权重固定为 110，远高于普通 class（10） - 支持多主题扩展：
data-theme="amber"直接启用第三套配色，不用改 CSS 类名 - Safari 旧版对
@media (prefers-color-scheme) .dark :root支持不稳定，但[data-theme]全系兼容
JS 切换时最容易漏掉的三件事
不是设了 dataset.theme 就完事——以下任一疏漏都会导致主题不生效：
- 没在
<head>内联<script>中预设初始值：<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script>，否则浏览器先按无主题渲染，再 JS 补切，必然闪屏 - 没监听系统偏好变更：
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', ...)，用户系统级切换后页面不同步 - 没处理 localStorage 与 DOM 同步：比如用户手动清空 localStorage，但
dataset.theme还残留旧值，导致 UI 和存储状态不一致
主题变量命名与维护的实际约束
变量名一旦上线就别轻易改，尤其带前缀的（如 --ant-primary-color），下游组件、第三方库、甚至埋点脚本都可能依赖它。改名=全量回归测试。
建议做法：
- 统一用语义化前缀，如
--theme-bg、--theme-text，避免--main-bg这类模糊命名 - 深色模式变量不要只写“暗色值”，而要显式标注用途：
--theme-bg-dark而非--bg-dark - 禁用 CSS 预处理器生成变量（如 Sass
@for循环批量定义），构建时无法提取，调试困难，且不利于运行时 JS 动态读取
最易被忽略的点：变量值本身不能含单位或函数（如 --gap: calc(1rem + 4px) 在某些 SSR 场景下会被解析失败），纯数值/颜色/字符串最稳妥。
