动态切换主题的核心是用CSS自定义属性统一管理颜色变量，通过切换:root或类名来响应式更新，配合prefers-color-scheme兜底、localStorage持久化及可访问性校验确保体验一致。
用 CSS 自定义属性（--color-primary）统一管理主题色
动态切换主题的核心不是写两套 CSS，而是把所有可变颜色抽成 --* 变量，再通过 :root 或特定 class 控制它们的值。比如深色模式下 --bg 设为 #1e1e1e，浅色模式下设为 #ffffff。这样只需切换根节点 class，整页颜色自动响应。
关键点在于变量命名要有语义、不带具体颜色值，例如：--text-primary 而不是 --text-white；否则换主题时还得改类名，失去“动态”意义。
- 所有主题相关颜色必须只出现在
:root或主题 class 内，禁止在组件里硬写color: #333 - 避免用 HSL/RGB 直接计算明暗——浏览器不支持运行时颜色运算，得靠 JS 或预设好两套值
- 变量可分层：基础色（
--color-blue-500）、语义色（--color-primary）、场景色（--color-card-bg），后者引用前者
用 @media (prefers-color-scheme) 自动适配系统偏好
用户没手动切主题时，靠这个媒体查询兜底最稳妥。它不依赖 JS，CSS 原生支持，且在页面加载初期就生效。
注意它只响应系统设置，不能覆盖用户主动选择的主题（比如页面右上角点了“深色模式”）。所以得和手动切换逻辑共存，优先级要明确：手动 > 系统。
立即学习“前端免费学习笔记（深入）”；
- 默认
:root定义浅色变量，再用@media (prefers-color-scheme: dark)覆盖 - 不要在
@media里写完整样式块，只重设变量值，保持逻辑集中 - 部分旧版 Safari 对嵌套
@media+:root支持不稳定，建议把深色规则直接写在:root.dark类里更可靠
JS 切换主题时操作 document.documentElement.classList
手动切换本质就是给 元素增删 light / dark 类，然后让对应 CSS 规则生效。别去遍历所有元素改 style，也别用 JS 逐个设 cssText。
保存用户偏好到 localStorage 是必须的，否则刷新就回退。但读取时机很重要——得在 CSSOM 构建前执行，否则会闪屏。
if (localStorage.theme) {
document.documentElement.classList.add(localStorage.theme);
} else if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
document.documentElement.classList.add('dark');
}
- 切换函数里先移除旧主题类（如
light和dark），再加新类，避免残留 - 调用
localStorage.setItem('theme', 'dark')后，立刻同步更新document.documentElement，不要等下次渲染 - 如果用了 CSS-in-JS 库（如 Emotion），确保它的主题变量也同步更新，否则样式会不一致
颜色对比度与可访问性不能靠“看起来差不多”判断
深色模式下，#ffffff 文字配 #121212 背景看似对比强，实际 WCAG 计算只有 15.5:1（超了），但 #e0e0e0 配 #121212 就只剩 7.2:1 —— 接近最低要求 4.5:1。人眼容易误判，必须用工具验证。
别用纯黑 #000000 做深色背景，OLED 屏幕易烧屏，且文字边缘发虚；推荐 #121212 或 #1e1e1e 这类偏灰黑。
- 用 Chrome DevTools 的 Accessibility 面板实时检查对比度，或插件 axe DevTools
- 按钮悬停态、禁用态的颜色变化也要单独测试，它们常被忽略
- 图标颜色若用
currentcolor，需确保父元素文本色已按主题正确设置，否则图标不会变
