CSS变量必须带功能前缀（如--ui-button-size-large）、禁用裸名，统一注入并设fallback，禁止用变量管状态，变量名与BEM类名映射但不套用其语法，所有变量需纳入构建链路。
变量必须带功能前缀，裸名如--color或--sm等于埋雷
大型项目里，--color这种命名一上线就容易撞车。不同模块各自定义，DevTools 里搜不到来源，构建后也难定位。Bilibili-Evolved 的 --be-、--ui-、--video- 不是装饰，是强制作用域隔离。
-
--color-、--space-、--radius-、--shadow-是一级功能前缀，不写--main-color这类模糊名 - 二级补全要语义清晰：
--color-text-primary而非--text-primary，避免和 JS 中的textPrimary变量混淆 - 组件级变量挂到组件根节点：
--ui-button-size-large，不是全局--button-size-large
变量名与 BEM 类名映射，但不套用 BEM 语法结构
--ui-button__text--large-size 看起来“很 BEM”，但这是错的。CSS 变量不继承 BEM 的 __/-- 层级语法，强行套用会让 IDE 补全失效、VS Code 搜索变慢、新人看不懂。
- 对应
.button--large，变量叫--ui-button-size-large - 对应
.button__icon，变量叫--ui-button-icon-size - Modifier 类名（如
.button--disabled）保留，但样式值由变量驱动：opacity: var(--ui-button-opacity-disabled)
别用变量管状态，--is-hovered 是反模式
CSS 自定义属性适合管“值”，不适合管“状态”。JS 动态设置 el.style.setProperty('--is-active', 'true')，再在 CSS 里写 [style*="--is-active:true"]——不可靠、不可调试、PurgeCSS 识别不了。
- 状态变化应靠 class 控制，变量只负责注入值：
.button--loading { background-color: var(--ui-button-bg-loading); } - 用
data-属性配合变量做开关（如[data-state="loading"] { --ui-button-bg: ... }）绕过 class 系统，破坏 BEM “类名即契约” 原则 - 布尔型变量如
--is-open在构建时无法静态分析，主题切换、SSR、Tree-shaking 全受影响
所有变量必须统一注入，不能靠人工维护多套 CSS 文件
深色模式切换时，不要写两份 :root：一份 light，一份 dark。这会导致变量散落、diff 难、CI 检查漏项。
立即学习“前端免费学习笔记（深入）”；
- 统一声明
--ui-button-bg，由 JS 根据主题动态赋值：document.documentElement.style.setProperty('--ui-button-bg', '#007bff') - 构建时注入（如 PostCSS 插件或 vanilla-extract 的
createThemeContract）比运行时 JS 注入更可控、可测试 - fallback 必须设：
var(--ui-button-bg, #007bff)，否则未注入时样式直接失效
--color-primary 就以为完事了，其实没定作用域、没配 fallback、没进构建链路，等于白写。 
