必须用[data-theme]而非.dark类，因其权重更高（110 vs 10）、无命名冲突、语义清晰、全浏览器兼容；需同步设置dataset.theme防FOUC；所有主题变量须在:root中完整显式声明，切换时仅改data-theme属性。
![如何通过css变量实现多套配色方案切换_利用[data-theme]属性动态映射](https://img.php.cn/upload/article/000/969/633/177830040747478.jpeg)
为什么必须用 [data-theme] 而不是 .dark 类？
因为 class 名容易冲突、优先级低、语义模糊。[data-theme="dark"] :root 的 CSS 权重是 110，远高于普通 class（10），且不会和业务中已有的 .dark、.theme-dark 或第三方组件的 class 打架。Safari 旧版对 @media (prefers-color-scheme) .dark :root 支持不稳，但 [data-theme] 全系兼容。多主题扩展也更干净：只要改 data-theme="amber"，不用新增 class 名或重写选择器。
document.documentElement.dataset.theme 必须在 HTML 解析前设置
否则浏览器先按默认样式渲染，JS 执行后再切主题，必然出现 FOUC（白屏闪动）。正确做法是在 中放内联 script：
<script>
document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';
</script>
注意三点：
- 不能等
DOMContentLoaded或load事件——太晚了 - 必须同步执行，不能包在函数里延迟调用
- 如果服务端能判断初始主题（如根据 Cookie 或 UA），优先服务端注入，更稳
所有主题变量必须在 :root 中完整声明，不能“按需定义”
比如你只在 [data-theme="dark"] :root 里写了 --bg-base 和 --text-emphasis，但没写 --border-color，那在暗色模式下所有用到 var(--border-color) 的地方都会 fallback 到初始值（可能是透明、继承色或 currentColor），导致边框消失或错色。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 每套主题都应覆盖同一组变量名，哪怕值和 light 模式相同也要显式写出
- 变量定义顺序无关紧要，但结构必须一致，方便 JS 批量读取或 JSON 驱动
- 不要在组件内部重复声明同名变量（如
.card { --bg-base: #f0f0f0; }），这会污染全局继承链
切换时只改 dataset.theme，别手动调 style.setProperty()
手动 setProperty 容易漏变量、难维护、无法回退。正确路径是：CSS 文件里用 [data-theme="dark"] :root 预设整套值，JS 只负责切换属性，让浏览器自动匹配并层叠生效。
典型错误：
- 只设
dataset.theme = 'dark'却忘了localStorage.setItem('ui-theme', 'dark')→ 刷新后失效 - 用
style.setProperty('--bg-base', '#111')替代属性切换 → 失去 CSS 层叠能力，后续媒体查询或主题扩展全乱 - 在
[data-theme="dark"]选择器外写变量（如直接写:root { --bg-base: #fff; }）→ 暗色模式下该变量仍生效，覆盖失败
真正关键的细节是：变量是否被所有上下文读取到，取决于它是否在 :root 下被 [data-theme] 选择器**完全覆盖**，而不是“有没有定义”。漏一个，就断一根颜色链。
