主题变量必须声明在:root上才能全局响应，切换时用document.documentElement.style.setProperty修改，避免局部作用域；border-width等需带单位的变量值不可省略单位；主题配置应存标识符而非整套变量；prefers-color-scheme变化需手动监听并触发更新。
主题切换必须用 :root 声明变量，别在局部作用域里改
直接在 <body> 或某个组件内部定义 --primary-color，切换时根本不会影响全局样式。CSS 变量的作用域是继承链，只有挂载在 :root（即 html 元素）上，才能被所有后代元素读取并响应式更新。
实操建议：
- 把所有主题色统一声明在
:root里，比如：:root { --primary-color: #007bff; --bg-color: #ffffff; } - 切换主题时，只修改
document.documentElement.style.setProperty()，不要操作 class 或重写整个 style 标签 - 避免用
body或组件级 selector 做变量宿主，否则button、input等原生元素可能拿不到值
color 和 background 能直接用变量，但 border 宽度不能
CSS 变量可以参与任何接受 CSS 值的地方，但不是所有属性都“兼容”变量语义。比如 border: 1px solid var(--primary-color) 没问题，但 border-width: var(--border-size) 中的 --border-size 必须是带单位的值（如 "2px"），不能只写 2 —— 否则计算会失败，浏览器静默忽略。
常见错误现象：
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 主题切换后边框消失，检查
getComputedStyle(el).borderWidth是否为"0px" - 变量值漏写单位，比如
setProperty('--gap', '8')→ 应该是'8px' - 颜色变量用于
box-shadow时，记得补全 rgba 或透明度，否则暗色主题下阴影可能不可见
HTML 预览场景下，localStorage 存主题名比存整套变量更可靠
预览页常要刷新后保持上次主题，如果把全部变量值（如 {"--primary-color": "#5a32a3", "--bg-color": "#121212"}）存进 localStorage，下次加载时得逐个 setProperty，容易漏或错序；更稳的方式是只存主题标识符，再靠 JS 映射回变量集。
使用场景示例：
- 定义主题配置对象：
const themes = { light: { '--primary-color': '#007bff', '--bg-color': '#fff' }, dark: { '--primary-color': '#4dabf7', '--bg-color': '#1e1e1e' } }; - 加载时读
localStorage.getItem('ui-theme') || 'light'，再批量 set - 避免在
DOMContentLoaded前执行 setProperty，否则部分元素可能已渲染完毕，不响应变量变更
暗色主题下 prefers-color-scheme 不会自动触发变量更新
即使你写了 @media (prefers-color-scheme: dark) { :root { --bg-color: #121212; } }，它只在页面首次加载时生效；用户手动切换系统主题，CSS 规则不会重跑，:root 变量也不会更新 —— 这是个常被忽略的兼容性盲区。
解决方案很简单：
- 监听
window.matchMedia('(prefers-color-scheme: dark)')的change事件 - 事件回调里调用一次主题切换逻辑（哪怕当前就是 dark，也重新 set 一遍变量）
- 注意：Safari 14+ 才支持该 media query 的动态监听，旧版需降级为手动开关
复杂点在于，用户既可能手动点主题按钮，也可能系统自动切，两套路径要共用同一套变量设置逻辑，别写两遍。
