应使用 html[data-theme="light"] 和 html[data-theme="dark"] 分别定义完整变量集，避免 :root 冲突；JS 切换 document.documentElement.dataset.theme 并持久化至 localStorage，优先级高于 prefers-color-scheme；禁用 box-shadow、display 等非主题语义属性变量。
怎么用 :root 定义主题变量并避免覆盖冲突
主题换肤本质是批量替换颜色、间距等基础值，:root 是最轻量的载体。但直接在多个 :root 块里重复声明同一变量，后加载的会覆盖前一个——哪怕它们属于不同主题类名下。真正可靠的做法是：所有主题变量统一挂在一个顶层选择器下，比如 html[data-theme="dark"] 和 html[data-theme="light"]，再各自内部定义完整变量集。
- 别写
:root { --color-bg: #fff; }+:root.dark { --color-bg: #111; }，因为:root本身已生效，.dark类无法覆盖它（除非加!important，但这是反模式） - 必须写成
html[data-theme="light"] { --color-bg: #fff; --color-text: #333; }和html[data-theme="dark"] { --color-bg: #111; --color-text: #eee; } - 变量名保持语义化，如
--color-primary而非--blue-500，否则换肤时要改一堆地方 - 所有组件样式都基于这些变量，例如
button { background: var(--color-primary); }，不写死颜色值
如何用 JavaScript 切换 data-theme 并持久化到 localStorage
切换主题不是改 CSS 文件，而是改 HTML 元素的属性，再靠 CSS 变量自动响应。关键在两步：更新 document.documentElement.dataset.theme，并把值存进 localStorage 避免刷新丢失。
- 不要用
document.body.className = 'dark'，这和你的:root规则不匹配，CSS 不会响应 - 正确写法：
document.documentElement.dataset.theme = 'dark'; - 存取逻辑建议封装成函数：
localStorage.setItem('theme', 'dark');，读取后立即应用，防止白屏闪动 - 首次加载时，优先读
localStorage，没值再 fallback 到系统偏好（window.matchMedia('(prefers-color-scheme: dark)').matches） - 注意 Safari 对
dataset的大小写敏感性：data-theme对应dataset.theme，不是dataset.Theme
为什么 prefers-color-scheme 不能替代手动切换
prefers-color-scheme 是系统级信号，只反映用户操作系统设置，和页面内“我点一下就变暗色”的交互意图无关。它适合做默认值，不适合当唯一控制源。
- 用户可能系统设的是暗色，但当前网站就想用亮色（比如阅读长文时更护眼），这时候强制跟随系统反而违背体验
- CSS 中写
@media (prefers-color-scheme: dark) { html { --color-bg: #111; } }是静态响应，无法被 JS 动态覆盖或撤销 - 如果同时用了
prefers-color-scheme和手动切换，建议让手动切换优先级更高：JS 设置data-theme后，CSS 规则必须明确高于媒体查询（靠选择器权重，比如用html[data-theme] { ... }） - 部分旧版 iOS Safari 对
prefers-color-scheme支持不稳定，仅依赖它会导致主题错乱
哪些样式属性不适合放进 CSS 变量做主题控制
不是所有视觉属性都适合用 var(--xxx) 管理。变量本质是字符串替换，遇到需要计算、条件判断或复杂结构的地方，容易失控。
立即学习“前端免费学习笔记（深入）”；
- 避免把
box-shadow整条值塞进变量，比如--shadow: '0 2px 4px rgba(0,0,0,0.1)';—— 一旦想微调透明度或颜色，就得重写整个字符串，没法复用 - 不要用变量控制
display或position这类布局开关，它们没有渐进变化，且语义和主题无关 - 字体族（
font-family）可以放，但注意引号问题：若值含空格，定义时需加引号，使用时font-family: var(--font-ui);会自动解析，无需额外包裹 - 动画相关属性（
transition,animation）慎用变量，浏览器对变量中动态时间/缓动函数的支持仍有兼容性风险
var()，而是确保所有组件样式都彻底剥离硬编码值，并在主题切换瞬间不出现样式抖动。这点常被忽略：CSS 变量是异步生效的，如果 JS 切换 data-theme 后立刻操作 DOM，某些元素可能还没完成重绘。 
