BEM本身不构建组件库，只定义类名映射结构与职责边界；真正高可维护的关键在于目录、文件、DOM、类名、修饰符五者严格对齐，缺一不可。
直接说结论：BEM本身不构建组件库，它只定义类名如何映射到组件的物理结构和职责边界；真正高可维护的关键，在于目录、文件、DOM、类名、修饰符五者严格对齐，缺一不可。
组件目录与块名必须一一对应
每个组件必须独占一个目录，目录名就是块名（全小写、中划线分隔），比如 button 组件只能放在 /components/button/ 下。这个目录里只允许出现 button.css、button.tsx、button.test.tsx 等归属该块的文件。
常见错误现象：
- 把
button__icon单独抽成/components/icon/——它不是独立块，只是button的元素，强行拆分会破坏语义闭环 - 在
button/目录里塞进card.css——CI 检查会立刻 fail - 用
Btn或btn-primary作目录名 ——大小写混用或带状态词，grep搜不到，协作链就断了
DOM结构必须满足“三名一致”硬约束
组件名、文件名、块名三者必须完全一致：Button.vue → button，不是 btn 或 ui-button。更重要的是，button 必须是可独立渲染的 DOM 节点（如 <button class="button"> 或 <div class="button">），不能只是包裹用的空 <div>。
立即学习“前端免费学习笔记（深入）”；
典型翻车点：
- 文档写“
card__header是卡片头部”，但没注明它是否允许嵌套card__title；结果开发者写了<div class="card__header"><h2 class="card__title">，样式却失效——因为card__title实际只接受card的直接子节点 -
button__text中间插了个<span>或框架<Fragment>，导致 CSS 选择器.button__text匹配失败
修饰符叠加必须有明确冲突规则
修饰符不是开关贴纸，button--primary 和 button--disabled 可以共存，但前提是 CSS 规则不依赖选择器权重（即必须写 .button--disabled { }，而非 .button.button--disabled { }）。
文档必须声明哪些能叠加、哪些互斥：
-
button--large和button--small互斥，需加 ⚠️：“二者不可同时使用，否则尺寸定义冲突” -
button__label--hidden合法（只影响 label 自身），但button--primary__label语法非法且语义混乱 - 禁止
button--loading这类暴露实现细节的修饰符；应统一用button--pending或button--busy，与业务状态对齐
SCSS嵌套必须守住单层封装底线
BEM 的核心是输出扁平类名，不是写视觉嵌套。Sass 的 & 很方便，但一不留神就会编译出后代选择器，破坏作用域隔离。
正确写法只允许单层嵌套：&__elem 和 &--mod：
.button {
&__text { font-weight: 600; }
&--large { padding: 12px 24px; }
}错误写法会产出 .button__text .button__icon 这种后代选择器，一旦 DOM 结构微调，样式就失效：
.button {
&__text {
&__icon { /* 编译后是 .button__text .button__text__icon */ }
}
}所有 Block 样式必须独占一个文件，如 _button.scss，禁止跨 Block 引用（如在 _button.scss 里写 .modal__close）。
最易被忽略的点：BEM 文档不是类名列表，而是模块契约说明书。漏写 DOM 层级约束、没标修饰符互斥关系、混淆 __ 和 -- 的语义边界，都会让下游开发者卡在真实项目里两小时，而且查不出问题根源。
