遮罩层必须命名为 modal__overlay 且与内容区同级，因二者共享状态、动画和关闭逻辑；独立命名或嵌套会破坏BEM规范、导致状态不同步、CSS误删及层叠上下文问题。
遮罩层必须是 modal__overlay，不能是独立 Block 或嵌套 Element；内容区必须与遮罩同级、同属一个 Block；所有状态控制（如显隐）必须作用于 Block 根节点。
为什么 modal__overlay 不能写成 overlay 或 modal__content__overlay
遮罩不是功能独立的组件，它和弹窗内容共享显隐状态、关闭逻辑（点击即关）、动画节奏。写成 overlay 独立 Block，JS 就得同时维护 modal--visible 和 overlay--visible，稍有延迟就会出现“遮罩已显、内容未动”的断裂体验。
modal__content__overlay 违反 BEM 铁律：元素不可嵌套。__content 若只是容器而非可复用 Block，title、body 等应直接为 modal__title、modal__body，中间层无意义，还会让 PurgeCSS 误删类名、VS Code 无法跳转。
- 正确结构：
<div class="modal"> <div class="modal__overlay"></div> <div class="modal__content"></div> </div> - 错误结构：
<div class="overlay"></div>或<div class="modal__content"><div class="modal__content__overlay"></div></div>
modal--visible 必须加在根节点上，而不是子元素
修饰符 --visible 表达的是整个模态框的状态，不是遮罩或内容的局部表现。加在 modal__overlay 上，会导致遮罩显示但内容不动；加在 modal__content 上，则遮罩可能被遗漏，失去语义闭环。
立即学习“前端免费学习笔记（深入）”；
CSS 应这样联动：
.modal--visible .modal__overlay { opacity: 1; visibility: visible; }
.modal--visible .modal__content { transform: translateY(0); }
- React 场景下，只需
classList.toggle('modal--visible')操作最外层div - 若内容需独立入场动画（如滑入），可用
modal__content--entering，但它必须由 JS 在modal--visible触发后同步添加，不可脱离主状态 - 禁止写
modal__overlay--visible：这会让状态粒度失控，且无法与modal__content动画同步
modal__overlay 的 CSS 必须绕开层叠上下文陷阱
Fixed 定位的遮罩常被压在其它元素下面，不是 z-index 写得不够高，而是父级或自身触发了新层叠上下文。常见诱因包括 transform、opacity、filter、will-change —— 即使只写 transform: translateZ(0)，也会让 z-index 失效。
-
modal__overlay必须挂载在下，或至少是/的直系子节点，避开所有带transform的祖先 - 定位推荐用
inset: 0，比四边分别写top/right/bottom/left更简洁、不易漏边（旧版 Safari 可回退） -
pointer-events要分层：遮罩本身设pointer-events: none，内部关闭按钮等可点元素单独设pointer-events: auto - 隐藏时禁用
display: none（不可过渡），改用visibility: hidden+opacity: 0，transition 必须定义在基础类中，而非--visible里
尺寸、位置、主题等修饰符只能作用于 Block 根节点
尺寸不是内容区的属性，而是整个模态框的布局约束。写成 modal__content--large 会破坏 padding、border、字体大小的协调性，导致按钮溢出或留白错乱。
- 正确写法：
modal--large、modal--centered、modal--dark，全部直接作用于.modal - Block 名建议用
dialog替代modal，避免与第三方库（如 ant-modal）或业务组件（notification-modal）冲突 - 皮肤类（如
dialog--dark）不应影响dialog__overlay的背景色——遮罩色应由 overlay 自身规则控制，保持语义分离
真正难的不是命名，而是把「遮罩和内容属于同一交互单元」这个事实，通过 HTML 结构、CSS 类名、JS 状态三者完全对齐。一旦某处脱节（比如 DOM 中 modal__overlay 被提到了 body 外层，或 JS 用两个 state 分别控制显隐），BEM 就只剩空壳。
