唯一能真正统一主题颜色的路径是在 :root 中定义语义化变量（如 --color-primary）并显式调用 var(--color-primary)；其他方式均会导致漏控、失效或维护雪崩。
直接在 :root 中定义语义化变量（如 --color-primary），并确保所有用色位置显式调用 var(--color-primary)，才是唯一能真正统一主题颜色的路径。其他方式——比如只改 JS 颜色值、靠 class 覆盖局部样式、或在组件内零散声明变量——都会漏控、失效或导致维护雪崩。
必须在 :root 里声明，且只声明不嵌套
浏览器把 :root 当作最高层级作用域，变量天然可被所有后代继承。写成 .theme { --color-primary: #007bff; } 或 html.theme { --color-primary: #007bff; } 都不行，子元素取不到。
-
--color-primary必须以双短横线开头，写成color-primary浏览器直接忽略 - 避免在
:root里引用其他变量，例如--color-text: var(--color-primary);——部分旧版 Safari 会解析失败 - 所有基础色（主色、文字、背景、边框）都得在
:root里给默认值，不能等主题类加载后再补，否则首屏渲染就是错的
var() 必须带合法 fallback，且 fallback 不是“兜底逻辑”
var(--color-primary, #333) 的第二个参数只在变量未定义、为空或语法错误时生效；它不是“变量不存在就走这里”的条件分支。一旦你动态删掉 --color-primary，所有依赖它的地方都会立刻降级到 #333，UI 可能突变。
- fallback 值必须是合法 CSS 值：
var(--color-bg, transparent)✅，var(--color-bg, unset)❌ - 别把
var()当唯一值用在关键属性上，比如color: var(--text-primary);没 fallback，变量失效时可能继承父级色，变成不可读的灰 - 复杂属性建议拆开写：
border: 1px solid var(--color-border, #ddd);比border: var(--border-rule, 1px solid #ddd);更可控
哪些地方最容易漏掉 var() 替换
主题色不只出现在 .btn 或 .header 这类显眼选择器里。漏一处，那一块就卡在旧主题里，且很难被肉眼发现。
立即学习“前端免费学习笔记（深入）”；
-
::before/::after的background和color—— 下划线、状态标记、图标装饰常在这里硬编码 - SVG 内联的
fill和stroke：必须显式写fill: var(--color-primary);，不能指望继承 - 表单控件状态：
input:focus的outline-color、button:disabled的background-color - 第三方库（如 Ant Design、Element Plus）若没开启 CSS 变量支持，其内部 class 不响应你的变量，需额外加覆盖规则
动态切换时，document.documentElement.style.setProperty 是最稳路径
比起给 html 加 class="theme-dark" 再写一堆覆盖规则，直接操作 :root 变量更轻量、更可靠。变量更新后，所有依赖它的样式自动重计算，不用手动触发重绘。
- 批量设置推荐用对象注入：
Object.entries(theme).forEach(([k, v]) => doc.documentElement.style.setProperty(k, v)) - 变量名在 JS 和 CSS 中必须完全一致，拼错（比如
--primary-colorvs--color-primary）浏览器静默忽略，不报错也不生效 - 旧版 Safari 有 CSS 变量缓存丢失问题，切换后偶现闪屏，建议搭配
transition: color .2s, background .2s;缓解
真正难的不是写几行 :root，而是让每个新写的样式都条件反射地用 var()，并在每次引入第三方组件时主动检查它是否响应你的变量体系——这决定了换肤成本是改一行，还是改三十个文件。
