必须用[data-theme]而非.dark类控制皮肤，因其选择器权重更高（110>10）、无命名冲突、语义化且兼容性好；需在HTML解析前通过内联script设置dataset.theme防FOUC；所有主题变量须在:root中完整显式声明。
为什么必须用 [data-theme] 而不是 .dark 类控制皮肤
因为 [data-theme="dark"] 的 CSS 选择器权重是 110，而 .dark 只有 10。业务中随便一个 .header .nav-item.active 就能压过它，导致变量覆盖失败。更关键的是，.dark 容易和第三方 UI 库（比如 Element Plus 的 .el-dark）或你自己写的 .theme-dark 冲突；[data-theme] 是语义化属性，无命名污染，全浏览器兼容，包括 Safari 旧版本对 @media (prefers-color-scheme) 的不稳定支持也能被兜住。
document.documentElement.dataset.theme 必须在 HTML 解析前设置
否则必然 FOUC（白屏闪动）。浏览器先按默认样式渲染，JS 才执行，用户会看到一秒亮色 → 瞬间变暗色。正确做法是在 <head> 里放同步内联 script：
<script>
document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';
</script>
注意三点：
- 不能等
DOMContentLoaded或window.onload—— 太晚了 - 不能包在函数里延迟调用，比如
setTimeout(() => { ... }, 0) - 服务端能判断就优先服务端注入（如根据 Cookie 或 UA），比客户端更稳
所有皮肤变量必须在 :root 中完整显式声明
你不能只在 [data-theme="dark"] :root 里写 --bg-base 和 --text-emphasis，却漏掉 --border-color。一旦漏了，用到 var(--border-color) 的地方就会 fallback 到初始值（可能是透明、继承色或 currentColor），边框直接消失。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 每套主题都应覆盖同一组变量名，哪怕值和 light 模式相同也要显式写出
- 变量定义顺序无关紧要，但结构必须一致，方便后续 JSON 驱动或 JS 批量读取
- 别在组件内部重复声明同名变量（如
.card { --bg-base: #f0f0f0; }），这会污染全局继承链
切换皮肤时只改 dataset.theme，别碰 style.setProperty
手动调用 document.documentElement.style.setProperty('--bg-base', '#111') 看似直接，实际埋雷：容易漏变量、无法回退、失去 CSS 层叠能力，后续加媒体查询或新主题全乱套。
正确路径是：
- CSS 文件里用
[data-theme="dark"] :root预设整套变量值 - JS 只负责
document.documentElement.dataset.theme = 'dark' - 让浏览器自动匹配选择器、层叠生效、重计算所有
var()
典型错误：
- 只设
dataset.theme = 'dark'却忘了localStorage.setItem('ui-theme', 'dark')→ 刷新后失效 - 用
setProperty替代属性切换 → 后续@media (prefers-color-scheme: dark)无法叠加生效
最易忽略的一点：伪元素（::before）、SVG 的 fill 和 stroke 不自动继承 CSS 变量，必须显式写 fill: var(--text-color) 才能响应切换。
