必须用:root声明CSS全局变量，因其是浏览器唯一认可的文档根锚点，确保伪元素、SVG、Shadow DOM等所有场景均可继承；其他位置声明会导致漏色、失效或静默错误。
必须把所有颜色变量定义在 :root 里，否则伪元素、SVG、表单控件、Shadow DOM 内部都会漏色或失效。
为什么只认 :root，其他地方都不行
浏览器只把 :root 当作全局继承起点——var(--color-primary) 能在 ::before、svg、input::placeholder 里取到值，全靠它。写在 .theme-dark 或 body 里，JS 调用 document.documentElement.style.setProperty() 就完全没反应；写在组件选择器里（比如 .button { --color: red; }），兄弟组件根本读不到，还容易被覆盖。
-
:root是唯一能穿透伪元素和 SVG 的作用域锚点 -
.theme-dark :root可以，但.theme-dark本身不能声明变量 - 构建工具（Vite/Webpack）要确保
variables.css是第一个@import或<link>，否则第三方库的:root会压掉你的定义
:root 里变量怎么命名才不翻车
别用 --blue-500、--main-color 这类名字。前者耦合设计稿编号，换配色方案就得全局搜替换；后者语义模糊，main 到底是按钮？标题？还是背景？协作时全靠猜。
- 按用途分层：
--color-primary（主操作色）、--color-text-primary（正文文字）、--color-border-divider（分割线） - 状态衍生色尽量用
calc()动态生成：--color-primary-hover: hsl(var(--primary-h), var(--primary-s), calc(var(--primary-l) - 8%)); - 绝对避免短横线缺失：
--colorprimary拼错后调试时返回空字符串，很难排查
哪些地方最容易漏掉 var() 导致主题切换失败
最常出问题的不是按钮或卡片，而是那些“默认就有颜色”的元素：它们不显式声明，就靠浏览器样式或继承撑着，一换主题就卡死在旧值上。
立即学习“前端免费学习笔记（深入）”；
-
::before/::after的background-color、border-color、color全得手动写var(--color-primary) - SVG 图标必须加
fill: var(--color-primary); stroke: var(--color-primary);，内联 SVG 尤其容易忘 -
input:focus、select:disabled、button:active等伪类状态，每个都要查一遍是否用了变量 - 第三方 UI 库（如 Ant Design）得确认是否启用 CSS 变量支持；否则得用
:where(.ant-btn)强制覆盖
动态切换时怎么避免闪屏和抖动
直接改 --color-primary 的十六进制值（比如从 #1890ff 改成 #ff6b6b），悬停色、禁用色、文字对比度全脱节，用户眼睛会明显感觉到“跳”。
- 把主色拆成
--primary-h、--primary-s、--primary-l三个变量，换肤时只调l值（比如浅色模式57%→ 深色模式32%），色相和饱和度不变，观感稳定 -
transition不能写在变量名上（transition: --primary-color无效），要作用于具体属性：background-color: var(--bg-color); transition: background-color 0.3s ease; - 所有尺寸、圆角、间距变量也得在初始 CSS 中定义好，否则切换时 layout 会抖动
真正麻烦的不是写几行 :root，而是让每个伪元素、每张 SVG、每个第三方组件都对齐同一套语义变量——漏一个，主题就断一层。
