drawer__overlay必须是drawer组件的子元素而非独立block，需与drawer__content同级且挂载于drawer根节点下；drawer--open仅能作用于根元素；遮罩须用position:fixed+inset:0并绑定css自定义z-index。
drawer__overlay 必须是 element，不是独立 block
抽屉的遮罩层不能单独定义为 overlay 或 drawer-overlay 这类 block，否则会脱离 drawer 的状态控制链。它必须是 drawer__overlay，语义上明确“这是 drawer 组件的一部分”，而非全局浮层。DOM 中它得和 drawer__content 同级、同父容器，且都直接挂载在 drawer 根节点下。常见错误是把遮罩写成独立组件再 import 进来——结果 JS 控制 drawer--open 时，遮罩不响应；或者多个抽屉共用同一套 overlay--visible 类，一开全开。
drawer--open 必须加在根节点，不能加在子元素上
状态修饰符 drawer--open 只能作用于 drawer 这个 block 根元素，比如 <div class="drawer drawer--open">。这样 CSS 才能用选择器联动：<pre class="brush:php;toolbar:false;">.drawer--open .drawer__overlay { opacity: 1; visibility: visible; }
.drawer--open .drawer__content { transform: translateX(0); }</pre>
<p>若误加在 <code>drawer__overlay 上 → 遮罩显示但内容卡在左侧；若加在 drawer__content 上 → 内容滑出但遮罩仍是黑的。两者都会造成视觉断裂，且 JS 状态与 DOM 表现不同步。
drawer__overlay 必须用 position: fixed + inset: 0
遮罩层绝不能依赖父容器定位，也不能加 transform（哪怕只是 translateZ(0)）。只要它被包在带 transform、opacity 或 <code>will-change 的祖先里，就会创建新层叠上下文，导致 z-index 失效。正确写法只有：
.drawer__overlay {
position: fixed;
inset: 0;
background: rgba(0, 0, 0, 0.4);
opacity: 0;
visibility: hidden;
transition: opacity 0.25s ease, visibility 0.25s step-end;
}
注意：transition 必须写在基础类里，不能只写在 drawer__overlay--visible 中，否则隐藏时会突变。
层级要用 CSS 自定义属性绑定，别硬写 z-index: 9999
所有浮动组件的层级必须收口到 :root，例如：
:root {
--z-drawer: 1100;
--z-modal: 1000;
--z-toast: 800;
}
.drawer { z-index: var(--z-drawer); }
.drawer__overlay { z-index: calc(var(--z-drawer) - 1); }
这样做才能避免抽屉盖不住下拉菜单（dropdown）或被通知框（toast）压住。如果在 drawer__overlay 上直接写 z-index: 9999，一旦页面同时打开 drawer 和 modal，谁后渲染谁赢，完全不可控。
最常被忽略的一点：移动端手势拖拽抽屉时，drawer__content 的 transform 动画必须和 drawer 根节点的 z-index 提前对齐——因为加了 transform 就自动创建新层叠上下文，此时若 z-index 没设在根上，遮罩就永远盖不住内容区。
