CSS变量实现动态主题切换需定义在:root中，用setProperty修改，结合localStorage手动覆盖prefers-color-scheme，并按语义分层设计变量粒度。
CSS变量（Custom Properties）是实现动态主题切换最轻量、最原生的方案，不需要框架或构建工具介入，改一个属性就能批量更新所有关联样式。
定义主题变量时必须用 :root 作用域
只有在 :root 中声明的 CSS 变量才能被全局读取和动态修改。如果写在某个 class 或元素选择器里，JavaScript 修改后无法触发级联更新，会导致换肤失效。
- ✅ 正确写法：
:root { --primary-color: #4a6fa5; --bg-color: #ffffff; } - ❌ 错误写法：
.theme-dark { --primary-color: #1e3a5f; }—— 这个变量只在 .theme-dark 元素内部生效，且无法被外部 JS 统一控制 - 注意：浏览器会把
:root当作html元素的伪类，所以它天然具有最高继承优先级，适合做主题根变量
用 JavaScript 动态修改变量值要调用 setProperty
不能直接改 style 属性字符串，也不能用 cssText 覆盖，必须通过 setProperty 方法逐个设置，否则变量不会实时响应。
- ✅ 正确操作：
document.documentElement.style.setProperty('--primary-color', '#ff6b6b'); - ❌ 错误操作：
document.documentElement.style.cssText = '--primary-color: #ff6b6b';
—— 这会清空所有已有内联样式，包括其他自定义属性 - 批量更新建议封装函数，避免重复写
document.documentElement.style，例如：function setTheme(vars) { Object.entries(vars).forEach(([k, v]) => document.documentElement.style.setProperty(k, v)); }
深色模式适配要考虑 prefers-color-scheme + 手动覆盖逻辑
仅靠 @media (prefers-color-scheme: dark) 做自动切换不够——用户可能手动点“切到深色”，但系统仍是亮色；也可能系统是深色，但用户偏爱亮色主题。必须允许手动覆盖系统偏好。
立即学习“前端免费学习笔记（深入）”；
- 用 localStorage 记录用户最后一次选择，优先级高于系统偏好
- 初始化时先读 localStorage，再 fallback 到
matchMedia查询结果 - 不要用 class 切换（如
html.dark）来控制全部样式，那会重复维护两套规则；而是只用它来触发变量重设：if (savedTheme === 'dark') { setTheme({ '--bg-color': '#121212', '--text-color': '#e0e0e0' }); } - 注意：
matchMedia是异步监听，需用addEventListener('change')捕获后续系统切换，但用户手动换肤时要主动同步 localStorage 并触发 setTheme
真正难的不是写几行 setProperty，而是设计变量粒度——太粗（比如只定义 --theme-color）会导致组件无法独立控制语义色；太细（每个按钮都配一个变量）又难以维护。通常按语义分层：基础色（--color-primary）、功能色（--color-success）、中性色（--color-bg, --color-text），再加一层状态色（--color-primary-hover）。这样既灵活，又不至于失控。
