必须写在:root里，因为它是CSS规范定义的根作用域，确保所有后代元素无条件继承且跨框架、Shadow DOM复用；写在html或class中会导致作用域受限、优先级不足或兼容性问题。
直接在 :root 里定义 --color-primary 这类变量，并确保所有样式都用 var(--color-primary) 引用，是唯一能真正统一主题色的起点。其他方式——比如在组件里零散声明、靠 JS 动态改 styleSheets、或混用 SCSS/Less 变量——都会漏控、失效或编译报错。
为什么必须写在 :root 而不是 html 或某个 class 里？
:root 等价于 html 元素但优先级更高，且语义明确：它是 CSS 变量的“根作用域”。写在 .theme-dark 这类 class 里，变量只对该 class 及其后代生效；写在 body 或普通选择器里，子元素根本读不到。
- ✅ 正确：
:root { --color-primary: #1890ff; } - ❌ 失效：
.app { --color-primary: #1890ff; }→ 子组件.btn里color: var(--color-primary)拿不到值 - ❌ 隐患：
html { --color-primary: #1890ff; }→ 与:root冲突时可能被覆盖，且部分旧版 Safari 解析不稳定
var() 必须带 fallback，否则页面可能突然变黑或不可见
var(--color-text) 不校验变量是否存在。如果 --color-text 没定义，浏览器直接丢弃该声明，color 属性回退到 inherit 或默认值，文字可能消失或继承错误颜色。
- ✅ 安全写法：
color: var(--color-text, #333);—— 第二个参数是字面量 fallback，仅在变量未定义时生效 - ❌ 危险写法：
color: var(--color-text);—— 漏定义时无提示，调试困难 - ❌ 无效嵌套：
color: var(--color-text, var(--color-fallback));—— fallback 里不能写另一个var()，会被当作文本处理
主题切换时哪些地方最容易漏掉颜色引用？
主题色不只出现在 .btn 或 .header 这类显式组件里。很多样式是隐式继承或间接计算出来的，漏掉就会导致新旧颜色混杂。
立即学习“前端免费学习笔记（深入）”；
- 伪元素：
::before/::after的background、color、border-color需手动替换 - 表单状态：
input:focus的outline、select:disabled的背景色、button:active的阴影 - SVG 图标：
fill和stroke属性必须显式写成fill: var(--color-primary); - 第三方库：
Ant Design、Element Plus默认不响应你的--primary-color，需确认它们是否开启 CSS 变量支持，或通过:host/shadow-dom透传
HSL 分离方案能避免深色模式下的视觉跳变
直接换 --color-primary: #1890ff → #0056b3 会导致按钮悬停、禁用态等衍生色失配。用 HSL 拆解后，只需调 --primary-l（亮度），色相和饱和度保持稳定，观感更连贯。
- ✅ 推荐结构：
:root { --primary-h: 210; --primary-s: 100%; --primary-l: 57%; } - ✅ 衍生写法：
background: hsl(var(--primary-h), var(--primary-s), calc(var(--primary-l) - 10%)); - ⚠️ 注意：
var(--primary-s)值必须写成100%，不能加引号或空格，否则旧版 Safari 解析失败
真正难的不是定义变量，而是让所有样式——包括伪元素、SVG、第三方组件、JS 动态插入的节点——都严格走 var() 路径。一旦漏掉一处，主题切换就变成修图游戏。
