bem 文档靠约束而非撰写——通过代码审查、自动化检查和三类命名模板实现。block 全小写连字符，element 用双下划线且不带逻辑词，modifier 仅描述状态/外观；eslint/stylelint 硬性校验，目录结构即契约，禁止跨层级命名。
直接说结论：BEM 文档不是写出来的，是约束出来的——靠代码审查 + 自动化检查 + 三类命名模板，而不是靠长篇规则说明。
为什么 BEM 命名文档容易失效
多数团队写的 BEM 规范文档最后变成 PDF 存档，没人看，因为问题不在“不知道规则”，而在“改个 class 名要查文档、要猜语义、要问同事”。真实瓶颈是：命名决策成本高、重构时不敢动、新人加个 header__title--big 就破坏层级语义。
真正起作用的不是文档页数，而是：
• 提交前自动拦截非法命名（比如 btn-primary--large 没有 block 上下文）
• IDE 里输入 card__ 时自动提示合法修饰符（card__image / card__content）
• Code Review 时只问一句：“这个 class 能在 card 组件外复用吗？”
只保留三类可执行的命名模板
把所有 BEM 场景压缩成三个填空式结构，开发时照着套，不自由发挥：
-
Block：全小写 + 连字符，必须能独立存在 ——
search-bar✅，user-profile-card✅，SearchBar❌，searchBar❌ -
Element：
<block>__<element></element></block>，双下划线，元素名不带逻辑词（避免header__title-wrapper）——header__title✅，header__title-text✅，header__title-container❌ -
Modifier：
<block>--<modifier></modifier></block>或<block>__<element>--<modifier></modifier></element></block>，仅描述状态/外观，不描述位置或父级关系 ——button--disabled✅，button__icon--rotated✅，button--mobile❌，sidebar__item--first❌
用 ESLint + stylelint 实现硬性约束
文档里写一百条“不要嵌套超过三层”，不如让 stylelint 报错。关键配置项：
- 启用
stylelint-selector-bem-pattern插件，正则设为^(?:[a-z][a-z0-9]*)(?:-[a-z0-9]+)*(__[a-z][a-z0-9]*)(?:-[a-z0-9]+)*(?:--[a-z][a-z0-9]*)(?:-[a-z0-9]+)*$（适配你团队的连字符风格） - 禁止
class属性中出现空格分隔多个 block（如class="header search-bar"），强制用header__search-bar或独立 block - 在
eslint-plugin-react中开启react/no-unescaped-entities之外，加自定义 rule 检查 JSX 中 class 字符串是否匹配 BEM 正则（例如拦截className="btn primary"）
示例报错信息必须具体：Invalid BEM class 'userCard__avatar--large': modifier '--large' not allowed on element 'userCard__avatar' —— 不说“不符合规范”，直指哪部分违规。
组件目录结构即命名契约
文件路径就是隐式文档。一个 card 组件的目录必须长这样：
components/
└── card/
├── card.css
├── card.js
├── card__header.css
├── card__body.css
└── card__footer.css
如果出现 card__header__title.css，就违反了 BEM 原则（header 是 element，不能再有子 element），CI 直接 fail。同理，card--featured.css 可以存在，card-header--sticky.css 不允许 —— 因为 card-header 本身不是 block。
复杂点在于：当多个组件共用同一视觉样式（比如所有 __title 都需要统一字号），别提取公共 class，而是用 CSS 自定义属性 + :where() 控制，保持 class 名称语义纯净。否则，命名权就从组件移交给了设计师的视觉稿，BEM 就退化成“换个名字而已”。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
