CSS自定义属性是主题切换最轻量灵活的方式，通过:root定义变量、data-theme控制切换、localStorage持久化，并需确保回退值、作用域和层叠顺序正确。
用 CSS 自定义属性（CSS Variables）管理主题变量
主题切换本质是批量替换颜色、背景、文字等样式值，硬编码多套 class 或重复写 CSS 规则极难维护。CSS 自定义属性是目前最轻量、最灵活的实现方式，所有主题色统一定义在 :root 下，切换时只需修改这些变量值。
- 把基础色、语义色（如
--color-primary、--bg-surface、--text-default）全部声明在:root中 - 组件样式中只使用
var(--color-primary)，不写死具体颜色值 - 深色模式可额外定义一个
[data-theme="dark"]选择器块，覆盖:root中的变量值 - 注意：自定义属性不支持 CSS 动画过渡，颜色渐变更需借助 JS 控制 class 切换 + transition 属性作用于实际 color / background-color
通过 document.documentElement.setAttribute() 切换主题 class
JS 控制主题切换的核心动作不是改 style，而是切换根元素上的 data 属性或 class，触发 CSS 重计算。推荐用 data-theme 而非 class，语义更清晰且避免 class 冲突。
- 初始化时读取 localStorage 中保存的主题偏好：
localStorage.getItem('theme') - 设置主题时调用：
document.documentElement.setAttribute('data-theme', 'dark')或'light' - 同步写入 localStorage，确保刷新后保持：
localStorage.setItem('theme', 'dark') - 不要直接操作
document.body.className，容易覆盖其他业务 class - 若需支持系统级深色偏好，可用
window.matchMedia('(prefers-color-scheme: dark)')监听并 fallback
处理 CSS 变量未生效或回退失败的问题
常见现象是切换后颜色没变，或深色模式下部分元素仍是亮色——多半是变量作用域或回退值缺失导致。
- 确保所有用到变量的地方都写了回退值，例如：
color: var(--text-default, #333);，否则变量未定义时会显示透明或浏览器默认色 - 检查是否误将变量定义在局部选择器内（如
.card { --color-bg: #fff; }），这会导致子元素无法继承，必须放在:root或对应祖先上 - 深色模式 CSS 块必须放在 light 主题之后，否则层叠顺序导致覆盖失败
- 图片、SVG 的 fill / stroke 若依赖主题色，需显式用
fill: var(--icon-primary)，不能靠 inherit
自定义配色如何安全注入并持久化
用户手动选色属于运行时动态主题，不能靠预设 CSS 块覆盖，需要把颜色值实时写入 style 标签或 :root style。
立即学习“前端免费学习笔记（深入）”；
- 优先用
document.documentElement.style.setProperty('--color-primary', '#4a6fa5')，比插入 style 标签更可控 - 每次 setProperty 后，记得同步更新 localStorage，格式建议为 JSON 字符串：
localStorage.setItem('customTheme', JSON.stringify({ '--color-primary': '#4a6fa5', ... })) - 页面加载时先检查 localStorage 是否有自定义主题，有则逐个 setProperty；无则按系统或默认主题初始化
- 避免把用户配色直接拼进字符串再 innerHTML 到 style 标签，XSS 风险高且难以调试
- 注意：CSS 变量名区分大小写，
--Color-Primary和--color-primary是两个变量
