BEM 是块元素修饰符，需明确 Block 的物理范围与复用契约：Block 必须是独立可渲染 DOM 节点，命名与文件名一致；Element 仅限直接子节点，禁止嵌套；Modifier 仅作用于 Block 或其直属 Element，须声明叠加规则与冲突警告；错误示例需附真实报错线索。
直接写“BEM 是块元素修饰符”这种定义，文档就废了一半——它没告诉开发者 card__title 该挂在哪、button--disabled 能不能和 button--large 同时用、header__nav 和 nav 到底算不算同一个东西。
怎么写清 Block 的边界，而不是只列类名
文档里不能只写「按钮组件使用 button 作为 Block」，得明确 Block 的物理范围和复用契约：
-
button必须是独立可渲染的 DOM 节点（比如<button class="button">或<span class="button">），不允许仅作为 CSS 布局容器存在 - Block 名必须与组件文件名/模块名一致：Button.vue →
button，不是btn或ui-button - 如果某个 UI 单元在多个上下文出现且行为一致（如
icon出现在按钮、导航、弹窗中），它就必须是独立 Block，不能塞进button__icon或nav__icon
Element 文档必须标注 DOM 层级约束
光写「button__text 表示按钮内文字」不够，要注明它在 HTML 中的合法位置：
-
button__text只能是button的**直接子节点**，中间不能隔<div>或<span> - 禁止出现
button__text__highlight—— Element 不允许嵌套 Element，这是结构越界信号 - 若设计稿中某处需要“带图标的按钮文字”，不能靠
button__text__icon解决，而应拆成两个并列 Element：button__text+button__icon
Modifier 文档要写明叠加规则和禁用组合
修饰符不是标签贴纸，文档必须声明哪些能共存、哪些会冲突：
立即学习“前端免费学习笔记（深入）”；
-
button--primary和button--disabled可叠加，但前提是 CSS 规则不依赖选择器权重（即必须用.button--disabled { }，而非.button.button--disabled { }） -
button--large和button--small互斥，文档需加⚠️警告：“二者不可同时使用，否则尺寸定义冲突” - 禁止出现
button__text--large—— Modifier 只能作用于 Block 或其直属 Element，不能降级到子元素内部
错误示例必须带真实报错线索
文档里的反例不能只说“这样不对”，要给出开发者真会遇到的线索：
-
header__logo在 footer 复用 → 构建时报 warning：“logo已被定义为独立 Block，请勿在header命名空间下重复声明” -
card__content__title→ 浏览器 DevTools 里看到样式未生效，检查发现实际生成了.card__content .card__content__title这种非法嵌套选择器 -
button--loading加上后按钮变透明但还能点击 → 文档对应条目要标出缺失项：pointer-events: none、cursor: wait
最常被跳过的其实是“Block 何时该拆分”的判断标准——不是看视觉是否嵌套，而是看这个单元能否脱离当前父级、在别处独立使用并保持语义不变。这点不写进文档，团队里永远有人把 user-card__avatar__upload-btn 当合理命名。
