必须用:root定义CSS变量，因其是规范定义的顶层作用域，确保全局继承可靠、JS可读写、兼容Shadow DOM；局部声明则受限于作用域无法全局生效。
直接在 :root 里定义语义化变量，再全局替换所有硬编码颜色值——这是初级项目配色失控时最快、最稳的救法。不改架构、不加构建工具，改完立刻生效。
为什么必须用 :root 而不是 html 或局部 class？
CSS 变量的作用域由声明位置决定。:root 是规范定义的顶层作用域，等价于 html 但语义更准、继承更可靠。写在 .theme-dark 这类 class 里，变量只在该 class 内有效；写在组件 scoped 样式（如 Vue 的 <style scoped>）里，会被隔离，var() 根本读不到。
-
:root声明的变量能被所有后代元素继承，包括 Shadow DOM 外部穿透场景 - JS 通过
document.documentElement.style.setProperty()修改时，只有:root上的变量才保证可写可读 - 避免把变量塞进
body或某个 wrapper div —— 那些不是“根”，继承链可能断裂
哪些颜色必须提前抽成变量？
别从“蓝-500”这种设计系统命名开始。初级项目优先覆盖以下 6 类基础语义色，它们出现在 90% 以上的样式中：
-
--color-primary：主操作色（按钮背景、重要链接） -
--color-text-primary：正文文字（非 placeholder、非 disabled） -
--color-bg-surface：卡片/模块/容器背景 -
--color-border：边框与分隔线 -
--color-success/--color-warning/--color-danger：状态色（至少保留一个，比如--color-success）
示例：
:root {
--color-primary: #4a90e2;
--color-text-primary: #333;
--color-bg-surface: #fff;
--color-border: #e0e0e0;
--color-success: #7ed321;
}
替换时最容易漏掉的 4 类地方
改完 :root 和几个显眼组件后，主题切换仍不彻底，大概率是这些地方没动：
立即学习“前端免费学习笔记（深入）”；
-
::before/::after伪元素里的background-color或color—— 它们常被当成“装饰”忽略 - 表单控件状态：
input:focus的outline、select:disabled的文字色、textarea的border-color - SVG 图标内联属性：
<svg><path fill="#4a90e2"/></svg>必须显式改成fill: var(--color-primary) - 第三方 UI 库的 class（如
el-button）—— 它们默认不响应你的变量，需查文档看是否支持 CSS 变量注入，否则得用:where(.el-button) { background-color: var(--color-primary) }强制覆盖
var() 必须带 fallback，且 fallback 要合法
color: var(--color-text-primary); 看似没问题，但一旦变量未定义（比如子应用没加载主题 CSS），Chrome 会继承父级文字色，Firefox 可能渲染为透明——文字直接消失。这不是 bug，是规范行为。
- 正确写法：
color: var(--color-text-primary, #333);✅ fallback 是具体颜色值，不是inherit或unset - 所有用到
var()的地方都加 fallback，尤其是color、background-color、border-color - fallback 不是给旧浏览器兜底（IE11 都支持
var()），而是防变量缺失导致样式崩塌
真正难的不是定义变量，而是确保每个该用 var() 的地方都用了——比如按钮的 :hover、:active、:disabled 状态，漏一个，换肤就露馅。这没法靠工具自动发现，得靠人工核对组件样式清单。
