必须用:root声明所有主题变量，:root[data-theme="dark"]覆盖值，js通过dataset.theme切换，var()必须带fallback，确保动态换肤原子、无闪屏、全组件同步。
直接用 :root 声明所有主题变量，别绕路
所谓“无构建步骤”，核心就是不依赖 SCSS/Less 编译、不生成多份 CSS 文件、不靠 Webpack/Vite 多入口打包。全部逻辑在浏览器运行时完成——前提是变量必须提前定义好，且作用域清晰。
常见错误是只在 .theme-dark 类里声明变量，比如：
.theme-dark {
--bg-primary: #121212;
--text-primary: #e0e0e0;
}
这样写，var(--bg-primary) 在未命中该 class 的元素上会 fallback 到继承值或 transparent，导致样式丢失。正确做法是：所有变量都显式写在 :root 里，哪怕浅色模式下值相同。
-
:root中定义基础值（如浅色主题） - 用
[data-theme="dark"] :root覆盖变量（注意选择器权重是 110，稳定可靠） - 避免用
.dark :root或body.dark :root，容易被业务 class 覆盖
用 document.documentElement.dataset.theme 控制切换，而非 class 切换
很多人习惯给 body 加 class="dark"，再写 .dark .btn { ... }，这本质是静态覆盖，不是动态主题系统。真要“动态”，就得让变量值本身变，而不是靠 class 触发另一套样式块。
正确路径是：
- 初始化时读
localStorage.getItem('ui-theme')，设document.documentElement.dataset.theme = 'dark' - CSS 中用
[data-theme="dark"] :root批量重设变量 - JS 切换时只改
dataset.theme，不操作 class、不 reload、不重新 fetch CSS - 监听
matchMedia('(prefers-color-scheme: dark)')，但仅在用户没手动选过主题时才响应
这样切换是原子的、无闪屏的，且第三方组件只要用了 var() 就自动适配。
每个 var() 都必须带回退值，否则 FOUC 不可避免
变量未定义时，color: var(--text-primary) 不是“保持原样”，而是计算为 inherit 或初始值（比如 color 是 black），极可能造成文字瞬间消失或背景变白——这就是 FOUC（Flash of Unstyled Content）。
解决方法非常具体：
- 所有
var()调用必须带回退，例如color: var(--text-primary, #333) - 回退值要选通用、安全的默认色（不是随便抄个设计稿里的值）
- HTML
里放内联 script 预设初始data-theme，抢在样式计算前执行 - 批量修改变量时，别循环调用
style.setProperty()，改用style.cssText一次注入，减少重排
第三方组件主题不一致？检查它是否消费了你的 var()
Ant Design、Element Plus、Chakra UI 等主流库默认不读你的 :root 变量。它们要么走自己的主题配置（如 ConfigProvider），要么用 CSS-in-JS 注入样式。
想让它们和你的主题同步，只有两个现实路径：
- 用官方提供的主题注入 API（如 Ant Design 5 的
theme配置项），并确保它底层也映射到同一套 Design Token 源 - 对不支持的组件，手动补一层 wrapper，用
style={{ backgroundColor: getComputedStyle(document.documentElement).getPropertyValue('--bg-card') }}拿值塞进去
最常被忽略的一点：你定义的 --color-brand 和组件内部写的 --ant-primary-color 是两套体系，不打通就永远不同步。真正难的不是切主题，而是让所有消费端——包括你自己写的组件、UI 库、图表库、甚至内联 SVG 的 fill ——都指向同一组变量源。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
