BEM规范手册必须直击开发痛点，明确回答类名能否提交、报错如何修复、老代码是否修改三问；需定义块名禁用泛义词、元素名限用名词、修饰符值可枚举无单位三条硬规则，并支持VS Code实时校验与自动修复。
直接说结论：BEM规范手册不是写给“想学CSS的人”看的，而是写给“正在改代码、要提交PR、被CI拦住”的人用的——它必须能回答「这个类名能不能提交」「报错提示怎么修」「老代码要不要动」三个问题，否则就是废纸。
为什么团队总在BEM命名上反复扯皮
根本原因不是理解不了block__element--modifier，而是手册里没明确边界。比如写.user-card__avatar--large没人反对，但写.user-card__avatar--in-modal就卡住：这是位置信息，还是状态？手册若只说“修饰符要语义化”，等于没说。工具链（如stylelint-selector-bem-pattern）也拦不住——它只认语法结构，不判业务逻辑。
常见错误现象：
-
.header__logo--mobile：把响应式断点当修饰符，后续加平板适配就得新增--tablet，违背原子化原则 -
.btn__icon--primary：元素上挂修饰符本无错，但primary实际属于按钮整体，不是图标的状态 -
.card--loading .card__content：用后代选择器破坏封装，导致.card--loading一删，内容样式全崩
手册里必须写死的三条硬规则
这三条是CI能自动校验、Code Review能一句话否决的底线，不能模糊。
立即学习“前端免费学习笔记（深入）”；
- 块名（block）禁止泛义词：
main、content、box、section全部拉黑；只允许小驼峰或中划线，如dashboard-layout、user-profile-card - 元素名（element）只接受名词：
__title✅，__show❌（这是JS控制的状态，该用is-shown这类状态类） - 修饰符（modifier）值必须可枚举且无单位：
--size-small✅，--width-200px❌；禁止含位置、设备、父级上下文，如--in-sidebar、--on-mobile
如何让手册在VS Code里实时起作用
开发者不会翻手册，但会在保存文件时看到红色波浪线。这就要求手册规则必须翻译成编辑器能执行的动作。
实操建议：
- 在
.stylelintrc.js中启用stylelint-selector-bem-pattern，并强制componentName正则为^[a-z][a-zA-Z0-9]+(-[a-z][a-zA-Z0-9]+)*$（禁用大驼峰、下划线开头、数字开头） - VS Code安装Stylelint插件，勾选
Auto Fix on Save，让.user_name自动转成.user-name，.button--red直接报错 - 为高频块名建代码片段（snippets），如输入
bem-card回车，自动输出card card__header card__body card--full-width等骨架类名
老项目接入时最易被忽略的兼容点
手册若只写“所有新组件必须BEM”，等于没写。真正卡住的是混用场景：一个页面里同时存在.user-list .item和.user-list__item，开发者根本分不清该用哪个。
必须在手册里写清：
- 第三方组件（如
Ant Design）必须用wrapper包一层：<div class="order-form__ant-picker-wrapper"><datepicker></datepicker></div>，后续样式只写.order-form__ant-picker-wrapper .ant-picker - 全局工具类（
.clearfix、.sr-only）豁免BEM，但必须统一放在src/styles/base/utils.css，且禁止在业务组件中新增 - legacy代码不动，但
git blame查到的修改行若涉及类名，必须补上BEM版本，例如原<div class="nav">改为<code><div class="header-nav">，旧类名保留用于兼容，新类名用于新增逻辑 <p>BEM手册的成败不在多厚，而在每一条规则是否对应一个具体文件路径、一个CI报错信息、一个VS Code自动修复动作。写错一个<code>_就失效的工具链，容不得“原则上”“建议”这类词。
