CSS变量作用域由声明位置决定，:root声明全局可用，选择器内声明仅对该元素及后代生效；命名需带组件前缀防冲突；JS更新应操作具体容器而非documentElement；回退值须为静态颜色，不可嵌套var()。
变量声明位置决定作用域范围
CSS变量的作用域不是由命名决定的，而是由它在哪个选择器里被声明决定的。:root声明的变量全局可读，但一旦你在.card里写--card-bg: #f8f9fa，这个值就只对.card及其后代生效——哪怕DOM结构很深，只要没在中间某层重新声明同名变量，子元素就读取这个值。
常见错误是把变量写在子元素上，比如.card-header { --card-bg: #e0e0e0; }。这会导致.card-body读不到它，因为变量只绑定在.card-header元素自身，不向上或向下继承。
-
.card { --card-bg: #f8f9fa; }→ 所有后代都能用var(--card-bg) -
.card > .card-header { --card-bg: #e0e0e0; }→ 仅该header及其伪元素能用，body读不到 -
:root { --card-bg: #f8f9fa; }→ 全局可读，但改一次全站响应，失去模块隔离能力
命名空间必须带组件前缀
变量名冲突是局部覆盖失效的最隐蔽原因。写--bg或--primary看似省事，但.sidebar和.notification都用它时，切一个主题，另一个也跟着变——这不是bug，是设计缺陷。
第三方库（如Element Plus的--ep-color-primary）自带前缀，说明这是工程实践共识。你自己的组件也得照做：
立即学习“前端免费学习笔记（深入）”；
- 正确：
--card-bg、--badge-status-color、--modal-close-icon - 错误：
--bg、--color-1、--theme-x - JS动态更新时也得保持前缀一致，否则
cardEl.style.setProperty('--bg', '...')根本不会影响var(--card-bg)
JS更新必须操作具体容器，不能碰documentElement
想让某个.card实例切换深色模式，调用document.documentElement.style.setProperty('--card-bg', '#333')会拉垮整页所有卡片。真正安全的做法是直接操作该DOM节点：
const cardEl = document.querySelector('.card.special');
cardEl.style.setProperty('--card-bg', '#333');
cardEl.style.setProperty('--card-text', '#fff');
批量更新更推荐Object.assign，比循环调用setProperty轻量，且不会清空已有内联样式：
Object.assign(cardEl.style, {
'--card-bg': '#333',
'--card-text': '#fff'
});
绝对别用cardEl.style.cssText = ''——它会抹掉所有内联样式，包括width、margin等非变量属性。
回退值只能是静态颜色，不能嵌套var()
color: var(--card-text, #212529)是安全写法；color: var(--card-text, var(--fallback-text))在旧版Safari里会让整条声明失效，文字变成透明或浏览器默认黑。
想强制走回退？得先显式设为unset：
.card { --card-text: unset; }
.card p { color: var(--card-text, #212529); }
回退值还影响SSR首屏：服务端渲染时若变量未注入，静态回退值能保证不闪动；嵌套var()则可能直接空白。
