直接改:root变量不触发重绘，主题切换失效；应通过data-theme类切换作用域、语义化命名变量、所有var()必须带字面量fallback。
直接在 :root 里堆变量、靠 JS setProperty() 切换，90% 的项目会掉进闪烁、失效、查不到值的坑里。真正高效的主题管理，核心是「用 class 控制作用域 + 语义化变量命名 + fallback 兜底」，而不是把变量当全局状态去改。
为什么直接改 :root 变量值会失效或不生效
浏览器不会因为 document.documentElement.style.setProperty('--color-bg', '#1a202c') 就重绘所有元素——变量是实时求值的，但样式引擎只在属性值实际变化时触发重排重绘。常见表现：颜色没变、:hover 失效、伪元素颜色错乱。
- 检查是否在 CSS 中写了
!important硬覆盖了变量，比如background-color: #fff !important;，它会切断var(--bg)链路 - 确认目标元素的父级（至少是
html或body）确实声明了该变量；CSS 变量靠继承，不是广播式生效 - 留意
@media (prefers-color-scheme: dark)和data-theme="light"同时存在时的优先级冲突——媒体查询规则可能被 class 规则覆盖，导致暗色变量压根没加载
主题切换必须用 class，而不是纯 JS 修改变量
推荐写法是定义主题类（如 html[data-theme="dark"]），并在该类下重写变量值。这样既触发样式重计算，又避免 JS 与 CSS 耦合过深。
- HTML 中统一用
，不要用class="dark"或body.className = 'theme-dark'——html是:root的宿主，更可靠 - CSS 中写：
:root { --bg-color: #ffffff; --text-color: #333; } html[data-theme="dark"] { --bg-color: #1a1a1a; --text-color: #f0f0f0; } - JS 切换只需：
document.documentElement.setAttribute('data-theme', 'dark')，不用碰setProperty
var() 必须带 fallback，且 fallback 不能是另一个 var()
color: var(--text-color) 在变量未定义时，不同浏览器行为不一致：Chrome 可能继承父级文字色，Firefox 可能渲染为透明——UI 直接消失。fallback 不是“可选”，是保命线。
- 合法写法：
color: var(--text-color, #333);、font-size: var(--font-size, 16px); - 非法写法：
color: var(--text-color, var(--fallback-color));（嵌套var()不被支持） - 注意单位一致性：fallback 带单位（如
16px）没问题，但像var(--size, 1rem)在 Safari 15.4 之前可能解析失败，建议统一用 px 或 em
HSL 拆分变量比十六进制更可控，但要注意 Safari 兼容写法
用 --primary-h: 210;、--primary-s: 65%;、--primary-l: 57%; 替代 --primary-color: #4a90e2;，能让悬停、禁用、深色模式等状态通过 calc() 动态生成，视觉更连贯。
- 所有 HSL 分量变量定义时**不能加引号**：
--primary-s: 65%;✅，--primary-s: "65%";❌（旧版 Safari 解析失败） - 调用时统一用
hsl(var(--primary-h), var(--primary-s), var(--primary-l))，不要混用字面量和变量，比如hsl(210, var(--primary-s), 57%) - 深色模式只需改
--primary-l，保持--primary-h和--primary-s不变，色相和饱和度稳定，观感不跳变
最常被忽略的点是变量命名的语义层级——--color-primary 是基础 token，--text-primary 是用途映射，两者不该混用；一个组件内部的 --card-padding 必须限制在 .card 作用域内，否则会污染全局。主题管理不是“把颜色收进 :root”，而是让每个变量知道自己该在哪生效、谁有权改它、失效时怎么兜住。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
