css变量必须定义在:root才能全局生效，引用时需带后备值，组件内禁止重复声明，动态修改仅对:root有效且需js配合，web components需显式继承。
:root 里定义，其他地方用 var() 引用——这是最简路径，但错一处就全失效。
变量必须定义在 :root 才能全局复用
很多人把 --primary-color 写在 body 或某个 class 里，结果按钮、卡片、表单各自读不到同一个值。浏览器只从祖先链向上查找变量，:root 是文档根节点，是唯一能保证所有元素都继承到的位置。
- ✅ 正确：
:root { --color-primary: #1890ff; } - ❌ 错误：
body { --color-primary: #1890ff; }（button不一定在body下，且 Web Components 更不认这个） - ⚠️ 特别注意：Web Components（如自研或 antd 的 shadow DOM 组件）默认不继承
:root变量，得靠:host { --color-primary: inherit; }显式承接
引用时必须带后备值，否则变量未定义会直接失效
var(--color-primary) 没写后备值，一旦变量没定义或拼写错误，属性就变成无效值（比如 color: var(--text-color); → color: inherit），样式塌陷却不报错，极难排查。
- ✅ 推荐写法：
color: var(--text-color, #333); - ✅ 多层 fallback：
background-color: var(--bg-surface, var(--bg-base, #fff)); - ❌ 危险写法：
font-size: var(--font-size-lg);（没 fallback，出错静默失败）
组件内部禁止重复声明同名变量
在组件样式里写 .button { --color-primary: #52c418; }，表面看是“设默认值”，实则是切断外部控制——主题切换、运行时换肤、父级定制全部失效。这不是封装，是硬编码。
- ✅ 正确姿势：组件只引用，不定义；默认值统一收口到
:root - ✅ 局部覆盖用属性选择器：
button[data-variant="ghost"] { --color-bg-surface: transparent; } - ❌ 自废武功：
.card { --radius: 8px; border-radius: var(--radius); }（外部无法再改这个圆角）
动态修改只对 :root 生效，且需 JavaScript 配合
用 JS 改 document.documentElement.style.setProperty('--color-primary', '#722ed1') 才能触发重绘；改其他选择器上的变量（比如 document.body.style.setProperty）不会影响后代元素，因为变量继承链断了。
- ✅ 动态主题切换必须操作
document.documentElement - ✅ 暗色模式可配合属性切换：
document.documentElement.setAttribute('data-theme', 'dark')，再用[data-theme="dark"] { --color-bg: #1f1f1f; } - ⚠️ 注意：CSS 变量不能用于
@keyframes动画值，也不能直接参与calc()中的单位混算（如calc(var(--size) * 2px)会报错，要写成calc(var(--size) * 2)+ 单位）
真正卡住人的从来不是语法，而是变量挂在哪、谁继承得到、谁被覆盖掉——这些细节不显眼，但一错就全盘失灵。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
