主题色变量必须定义在:root伪类中，css变量作用域为级联，仅挂载到:root才能全局生效；错误写法如:root .theme-dark会失效，正确应分别定义:root和.theme-dark下的变量。
主题色变量必须定义在 :root 伪类里
CSS 变量（自定义属性）的作用域是级联的，只有挂载到 :root 才能被整个文档读取。如果写在某个 class 或元素选择器里，切换时其他组件根本拿不到新值。
常见错误是把变量塞进 .theme-dark 这类 class 下：
:root .theme-dark { --primary-color: #1e3a8a; }——这不会生效，因为 :root 和 .theme-dark 是两个独立选择器，不构成嵌套关系。
正确写法是：
:root {
--primary-color: #3b82f6;
--bg-color: #ffffff;
--text-color: #1f2937;
}
.theme-dark {
--primary-color: #60a5fa;
--bg-color: #111827;
--text-color: #f9fafb;
}
这样，只要给 或 切换 class，所有用 var(--primary-color) 的地方都会响应更新。
HTML 根节点 class 切换要避免重绘抖动
直接用 document.documentElement.classList.toggle('theme-dark') 是最轻量的做法，但要注意：如果页面已渲染，且 CSS 变量只用于 color、background 等非布局属性，浏览器会触发「仅重绘」；一旦变量被用于 width、margin 或 grid-template-columns，就可能触发重排，造成卡顿。
确保主题变量只影响外观类属性：
- ✅ 推荐用途：
color、background-color、border-color、box-shadow - ❌ 避免用途：
height、padding、font-size（除非你明确需要响应式尺寸变化）
另外，不要在 JS 中反复 setAttribute 或 classList.replace，用 toggle 或 add/remove 明确控制更稳定。
JavaScript 切换逻辑要同步 localStorage 并监听系统偏好
用户切一次主题，下次打开还恢复成默认色，体验会断层。必须把选择存进 localStorage，并在页面加载时读取：
const savedTheme = localStorage.getItem('theme') || 'light';
document.documentElement.classList.add(savedTheme === 'dark' ? 'theme-dark' : 'theme-light');
同时建议兼容系统级暗色模式：
- 用
window.matchMedia('(prefers-color-scheme: dark)')检测初始状态 - 监听其
change事件，但只在用户未手动切换过时才自动响应（避免覆盖用户选择） - 判断依据可以是一个布尔标志
userPreferenceLocked，由用户点击按钮后置为true
否则，用户刚切到深色，系统夜间自动开启又切回浅色，会显得不可控。
CSS 变量 fallback 值不是可有可无的装饰
写 color: var(--text-color, #374151); 不只是为了容错，更是为了开发阶段可维护性。当变量名拼错、或某主题漏定义某个变量时，fallback 能防止整块样式崩坏。
特别注意这些易漏场景：
- 子主题扩展（如
.theme-dark .card里用了--card-bg，但:root没定义它） - 第三方组件未适配你的变量体系，直接写死颜色值，导致主题不统一
- 构建工具（如 PostCSS）误删未使用的变量（尤其在启用 treeshaking 时）
所以每个 var() 都该带 fallback，哪怕只是临时占位，比如 var(--border-radius, 0.5rem)。
变量名层级和 fallback 的严谨程度，往往决定了主题系统后续能不能加皮肤、能不能交给产品配置化——而不是每次改色都要改三处代码。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
