可覆盖的CSS组件API依赖BEM命名契约、语义化修饰符和CSS变量三层配合：修饰符须为可枚举状态（如button--primary），禁用视觉直译（如button--red）；变量绑定Block根节点并仅定义接口；组件边界必须清晰，避免伪Block污染。
可覆盖的 CSS 组件 API 不是靠“留钩子”或“加!important”实现的，而是靠 BEM 的命名契约 + 修饰符语义 + CSS 变量三层配合；写错任意一层，比如用 .button--red 而非 .button--primary，就等于提前关闭了主题切换和运行时覆盖的能力。
修饰符必须是语义化、可枚举的状态，不能是视觉直译
修饰符（--）不是样式快照，而是对外暴露的可控开关。它要能被 JS 安全读取、被设计系统归类、被主题层统一接管。
-
.button--primary✅ 合法：表示“主操作态”，可映射到--button-bg: var(--color-primary) -
.button--red❌ 危险：把颜色值硬编码进类名，换品牌色时得全局搜替换，且无法用 CSS 变量动态覆盖 -
.button--large⚠️ 谨慎：尺寸属于响应式行为，应优先用@container或媒体查询控制；若必须提供，需配套定义--button-padding等变量，而非直接写padding: 12px - 禁止修饰符嵌套：
.button__icon--primary是错的——图标状态由按钮整体状态驱动，应通过.button--primary .button__icon或 CSS 变量继承实现
CSS 变量必须绑定到 Block 根节点，且只定义接口，不写具体值
BEM 本身不处理变量，但可覆盖性依赖变量注入点是否精准。变量不能散落在 Element 规则里，也不能在 Modifier 中重复赋值。
- 正确做法：
.button { --button-bg: var(--color-action, #007bff); --button-color: var(--color-on-action, white); } - 所有修饰符规则只改变量值：
.button--disabled { --button-bg: var(--color-disabled-bg); --button-color: var(--color-disabled-text); } - Element 只消费变量：
.button__icon { color: var(--button-color); }，不写color: white - 禁止在
.button--primary里直接写background: #007bff—— 这会让 JS 动态切换主题时完全失效
组件边界必须清晰，避免“伪 Block”污染可覆盖路径
一个类名能否被安全覆盖，取决于它是否真正代表一个独立、可测试、有明确定义边界的 Block。模糊边界会导致变量作用域错乱、修饰符无处挂载、覆盖逻辑被迫侵入子元素。
立即学习“前端免费学习笔记（深入）”；
- 合法 Block：
.date-picker（完整日历控件）、.user-card（含头像、姓名、状态的聚合单元） - 非法“伪 Block”：
.section-2（仅布局语义）、.card-header（没声明归属，实际应为.card__header） - 当某个 UI 单元需要独立覆盖能力（如统一修改所有提示文字颜色），它就必须是一个 Block：
.validation-message，而不是.form__error - 目录结构必须对齐：若存在
.user-card，就必须有/components/user-card/目录，且其 CSS 文件里不出现.button或.avatar类名 —— 否则覆盖时会误伤其他模块
真正难的不是写对 __ 和 --，而是每次加一个新修饰符前，得问清楚：这个状态是否在所有使用场景下都可预期？它的变量是否已被上游设计系统定义？有没有人会在 JS 里通过 el.classList.contains('button--loading') 做逻辑判断？漏掉任一环，所谓“可覆盖”就只剩一个看起来整齐的类名。
