CSS变量必须定义在:root中才能全局生效，因其依赖继承机制，:root即html根元素，确保所有后代可读取；写在其他选择器内会导致作用域受限而无法被按钮、弹窗等组件访问。
必须在 :root 中定义变量，且所有用色位置都得显式改用 var(--brand-color)，否则改了也没用。
为什么非得写在 :root 里？
CSS 变量靠继承生效，:root 就是文档根元素（等价于 html），它的自定义属性能被所有后代元素读取。写在 .app、body 或某个组件 class 里，变量作用域就锁死了——按钮、弹窗、SVG 图标全拿不到。
- 常见错误：把
--primary-color: #007bff放进.theme-wrapper，结果只有它内部的子元素响应 - IE11 也支持
:root，不用额外 polyfill - 别用
!important覆盖变量值，会切断级联链，JS 后续调用setProperty就失效
var() 必须手动替换所有硬编码颜色值
浏览器不会自动扫描旧样式去“升级”颜色。你得逐个找出来，替换成 var() 引用，漏一项，那一处就掉出主题体系。
- 要覆盖的属性包括：
color、background-color、border-color、box-shadow、outline-color - 伪元素容易漏：
::before和::after里的background或color得单独加var() - SVG 内联样式必须显式写：
fill: var(--brand-color)，否则不受影响 - 表单状态色如
input:focus、button:active常被忽略 - 第三方 UI 库（如 Ant Design）默认不走你的变量链，需确认其是否开启 CSS 变量支持
变量命名和分层怎么避免混乱？
直接塞一堆 --blue-500、--red-600 进 :root，后期维护会失控。推荐按语义+层级分组：
立即学习“前端免费学习笔记（深入）”；
- 基础色（设计源头）：
--color-blue-500、--color-gray-300—— 不直接用于组件 - 语义色（业务代码只用这些）：
--brand-primary: var(--color-blue-500)、--text-primary: var(--color-gray-900) - 状态色独立声明：
--state-success: #28a745，不依赖基础色变量 - 所有变量必须带默认值，比如
color: var(--text-primary, #333)，防 JS 动态设置失败时白屏
JS 动态换色时最容易栽在哪几个坑？
用 document.documentElement.style.setProperty 看似简单，但实际运行中问题密集：
- 变量名拼错（
--primary-colorvs--color-primary）浏览器静默忽略，无报错无提示 - 旧版 Safari 会丢 CSS 变量缓存，导致页面闪一下才变色
- 多个主题切换时，逐个
setProperty容易漏项；应把整套值存成对象，批量注入：Object.entries(theme).forEach(([k, v]) => doc.documentElement.style.setProperty(k, v)) - 构建时建议加
stylelint-custom-property-no-outside-root插件，防止变量误写在非:root下
最常被忽略的一点：暗色模式或用户自选主题不是“重写全部变量”，而是只覆盖差异项；:root 中的基础变量必须始终有默认值，否则未覆盖的变量会继承为 unset，渲染异常。
