CSS变量必须带作用域前缀（如--ui-button-bg）、禁用裸名和缩写、var()调用须配默认值、状态用class控制而非JS设布尔变量、变量须同步注入防止FOUC。
大型项目里 CSS 变量命名混乱，不是技术瓶颈，而是协作断点——变量名没带作用域前缀、语义模糊、跟 JS 保留字冲突，调试时 DevTools 里根本找不到定义来源。
为什么 --color 和 --sm 这类裸名必须禁用
裸名变量在多人协作中等于放弃可追溯性。--color 看似简洁，但没人知道它指主色、文本色还是边框色；--sm 在组件 A 里是 4px，在组件 B 里可能被重写成 8px，且无上下文提示。更糟的是，这类名字极易撞上其他模块的同名变量，而 CSS 没有报错机制，只会静默覆盖。
实操建议：
- 所有变量必须带一级功能前缀，如
--color-、--space-、--radius-、--shadow- - 禁用任何不带连字符分隔的缩写，
--clr、--sz不合法，--color-primary才是有效起点 - 构建阶段可用 PostCSS 插件扫描裸名，自动报错阻断上线
组件级变量该用 --ui-button-bg 还是 --button-bg
必须用 --ui-button-bg。前缀 --ui- 是命名空间隔离层，表明该变量归属 UI 组件域，和 --video-player-、--be-（Bilibili-Evolved）等形成平行作用域。只写 --button-bg，一旦设计系统引入 --button-bg 全局主题变量，或第三方库也声明同名变量，就直接失效。
立即学习“前端免费学习笔记（深入）”；
常见错误现象：
- 在
.button选择器里定义--button-bg，结果.modal .button里调用时发现值被:root里的同名变量覆盖 - VS Code 全局搜索
--button-bg，返回 27 个匹配项，却无法区分哪个来自按钮组件、哪个来自表单主题
正确做法：组件根元素上定义 --ui-button-bg，并在组件样式中显式使用：.button { background-color: var(--ui-button-bg); }
var(--text-primary) 为什么不加默认值就是生产事故
var(--text-primary) 在变量未定义时退化为 unset，不是继承父级颜色，也不是回退到浏览器默认值——它是真·透明，文字直接消失。尤其在动态主题切换或微前端场景下，JS 注入变量晚于 CSS 解析，首屏极大概率白屏或失色。
实操要点：
- 所有
var()调用必须配默认值：color: var(--text-primary, #333) - 默认值只能是 CSS 合法字面量，不能嵌套
var()，var(--text-primary, var(--text-fallback))无效 - 涉及
calc()的场景更要兜底：margin: calc(var(--space-md, 12px) * 2)，否则整个表达式计算失败
JS 动态设置 --is-hovered 是反模式
用 JavaScript 设置布尔型变量如 el.style.setProperty('--is-hovered', 'true')，再在 CSS 里写 [style*="--is-hovered:true"] 匹配，看似灵活，实则三重失效：PurgeCSS 删不掉、DevTools 查不到、媒体查询中无法响应 prefers-reduced-motion 等系统偏好。
真正可维护的做法是：
- 状态由 class 控制，变量只管值：
.button--hovered { background-color: var(--ui-button-bg-hover); } - 变量名不体现状态逻辑，只表达语义意图：
--ui-button-bg-hover而非--is-hovered - 深色模式等全局状态，统一用
:root.dark-theme或html[data-theme="dark"]类名切换，不要靠 JS 注入一堆布尔变量
最易被忽略的点：变量注入时机。所有变量必须在 HTML 加载完成前由构建工具注入 :root，或由初始化脚本同步写入 documentElement。靠 runtime 异步 fetch 配置再 setProperty，必然导致 FOUC 和样式断裂——这点在微前端子应用中尤为致命。
