组件根元素必须显式承载css变量，不能只靠:root声明；正确做法是将变量定义在组件选择器如.card { --card-bg: #fff; }中以实现作用域隔离，避免全局耦合，内联style="--var: value"最可控，命名须带组件前缀如--card-bg。
组件根元素必须显式承载CSS变量，不能只靠:root声明
很多开发者以为在:root里定义--card-bg，然后在.card-title里用var(--card-bg)就能生效——实际经常返回空值或继承失败。因为:root声明的变量虽全局可读，但继承链会被中间节点截断（比如.card没设color或background-color时，子元素可能无法正确解析var()）。真正可靠的做法是把变量绑定到组件容器本身：.card { --card-bg: #fff; --card-padding: 1rem; }。这样.card > .card-title才能稳定继承，且不会干扰.banner或.modal里同名变量。
常见错误现象：
- DevTools里“Computed”面板显示
var(--card-bg)解析为inherit或空字符串 - 用
getComputedStyle(el).getPropertyValue('--card-bg')返回空字符串 - 切换主题时所有组件一起变色，根本没法做局部覆盖
style="--var: value"内联注入比JS操作document.documentElement.style更可控
想动态改卡片背景色？别写document.documentElement.style.setProperty('--card-bg', '#222')——这只能影响:root里定义的变量，对.card { --card-bg: ... }完全无效。正确做法是在HTML模板里直接写内联变量：<div class="card" style="--card-bg: #f8f9fa; --card-border: #e9ecef;">。JS更新时只需<code>el.style.setProperty('--card-bg', '#222')，作用域精准、不触发全页重排、SSR也能直出。
使用场景：
- 服务端渲染（SSR）页面，避免首屏闪动
- 需要高频更新的动画变量（如拖拽偏移
--offset-x） - 多实例卡片各自独立配色，互不干扰
注意：别在标签里写style="--card-bg: #fff"，又在CSS里重复定义.card { --card-bg: #000 }——层叠规则下谁离得近谁生效，容易误判。
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
变量命名必须带组件前缀，拒绝--spacing-md这类泛义名
--spacing-md这种名字看似通用，实则埋雷：它在.card里是内边距，在.button里可能是行高，在.icon里又变成外边距。调试时看到var(--spacing-md)根本不知道它属于哪一层。正确命名要反映作用域和层级：--card-spacing-inner、--button-radius-sm、--icon-size-lg。
参数差异与影响：
- 全局变量（如
--primary-color）适合放:root，仅限品牌色、字体族等真正跨组件复用的值 - 组件级变量（如
--card-bg）必须定义在.card选择器内，否则等于放弃作用域隔离 - Web Components中优先用
:host { --card-bg: #fff; }，语义清晰且天然隔离
DOM结构没定死，CSS变量再规范也白搭
一个var(--size)在.button里控制字体，在.icon里控制宽高，这种同名异义会让调试变成猜谜。根本问题不在变量本身，而在HTML结构没提前约定好语义边界：比如<div class="card">
<h3 class="card__title"></h3>
<div class="card__body"></div>
</div>必须和.card { --card-title-font-size: 1.25rem; }严格对应。如果某处漏掉card__title类，或把标题塞进card__body里，变量就彻底失效。
最容易被忽略的是结构与变量的耦合度：没先画清DOM树，光堆var()和calc()，只会让组件在响应式切换、主题叠加或状态嵌套时失控。变量不是装饰，是结构契约的延伸。
