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"></button> 或 <span class="button"></span>），不允许仅作为 CSS 布局容器存在
• Block 名必须与组件文件名/模块名一致：Button.vue → button，不是 btn 或 ui-button
• 如果某个 UI 单元在多个上下文出现且行为一致（如 icon 出现在按钮、导航、弹窗中），它就必须是独立 Block，不能塞进 button__icon 或 nav__icon

Element 文档必须标注 DOM 层级约束

光写「button__text 表示按钮内文字」不够，要注明它在 HTML 中的合法位置：

CSS婚礼策划服务机构宣传网站模板

CSS婚礼策划服务机构宣传网站模板是一款适合提供婚礼策划和婚庆服务机构宣传网站模板下载。提示：本模板调用到谷歌字体库，可能会出现页面打开比较缓慢。

下载

• button__text 只能是 button 的**直接子节点**，中间不能隔 <div> 或 <code><span></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 当合理命名。