@xihan-ui/styles 1.0.0-alpha.1 → 1.0.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @xihan-ui/styles
 
+## 1.0.0-alpha.2
+
+### Major Changes
+
+- 934e126: 每份皮肤现在都能单独引入了，动画不再指望别处的文件在场。
+
+  `styles` 的 exports 逐组件铺了一百多条子入口，`import '@xihan-ui/styles/dialog.css'` 是受支持的用法。但 `xh-fade-in`、`xh-fade-out`、`xh-spin`、`xh-dialog-in/out` 这五支关键帧住在 `motion.css` 里，被 15 份别的皮肤引用——单独引入其中任何一份，动画名都查不到。`@keyframes` 的名字查找只认「文档里有没有这个名字」，查不到既不报错也不降级，看上去就是「这个组件没做动效」。`spinner.css` / `switch.css` / `popconfirm.css` 三处注释早就写明了这条理由，只是这五支没照办。
+
+  现在每份皮肤都自带它用到的关键帧。`motion.css` 因此空了，**已删除，`./motion.css` 子入口一并移除**——如果你显式引过它，删掉那行即可，它提供的关键帧已经跟着各组件走了。
+
+  新增 `check-keyframe-refs` 门禁盯住三件事：引用的动画名必须在同一份皮肤里定义、同名的多份定义必须逐字一致（名字是全局的，两份不同内容会互相覆盖）、关键帧必须写在 `@layer xihan.motion` 里（使用者按层覆盖时才盖得住）。
+
+  产物只大了 60 B：重复的关键帧对 gzip 几乎是免费的。
+
+### Minor Changes
+
+- 091bbef: 补上动效地基的四个缺口。
+
+  **减弱动效此前基本是失效的。** `tokens.css` 里一个 `prefers-reduced-motion` 都没有，降级靠 19 份皮肤各写各的 `@media`，而它们只把 `animation-duration` 压到 `0.01ms`——位移与缩放是写死的字面量，压时长压不掉。前庭不适恰恰来自大位移与缩放，所以「减弱动效」的用户看到的是瞬间跳完整段位移。现在幅度走 `--xh-motion-distance-sm/-md` 与 `--xh-motion-scale-enter`，令牌层在 reduce 下把它们归零，皮肤不必自带 `@media`。删掉 8 份已经冗余的降级块（含 8 条 `!important`）；marquee / skeleton / spinner 那几处有讲得通的自定义降级，保留。
+
+  **dialog 与 image-viewer 的退场动画从来没播过。** 皮肤给挂着退场动画的 `content` 补了 `[hidden]{display:none}`，收起时元素当场不生成盒子，动画不启动，退场探测器放弃申领租约、就地卸载。drawer 早就绕开了这个坑，它的注释还写着「与 dialog 一致」——而 dialog 恰恰是反的。现在真的一致了，四条退场动画同时补上 `forwards`。
+
+  **Web Components 端全域没有退场动画。** 三个浮层元素把收起写死在展开态上，与 `data-state="closed"` 同帧写内联 `display:none`。现在收起跟着 presence 走；Light DOM 下被拉长的不是节点存在的时间，而是可见的时间。
+
+  **破坏性程度**：进场缩放统一到 `0.96`（此前 0.98 与 0.96 混用），dialog / toast 进场 / color-picker 的起势略明显一点。button 的加载转圈不再被压成 `0.01ms`——转圈是「系统还在做事」的唯一可感知信号，压掉等于把加载态变成假死。
+
+  回归测试进了 `tests/browser/`：jsdom 不把样式表里的 animation 算进 `getComputedStyle`，这三件事在 jsdom 里结构性测不到。
+
+### Patch Changes
+
+- 7a5d898: 漏引皮肤不再静默：新增 `startSkinCheck()` 开发期探测与 `styles.missing-skin` 诊断码。
+
+  按需引皮肤时漏掉一行原本是这个库最难查的失效：那个组件的 `data-scope` / `data-part` 照常都在、
+  别的皮肤也确实加载了，只有它渲染成没有内边距、没有底色的裸元素，看起来像组件坏了而不是少引了一行。
+  这一条正是「按组件挑」在真实项目里立不住的根本原因。
+
+  每份组件皮肤现在在自己的 `[data-scope='X']` 上落一个 `--xh-X-skin` 标记（104 份）。
+  `startSkinCheck()` 扫页面上出现过的每个 scope，取不到标记就报诊断：
+
+  ```ts
+  if (import.meta.env.DEV) {
+    const { startSkinCheck } = await import("@xihan-ui/kernel/skin-check");
+    startSkinCheck();
+  }
+  ```
+
+  ```
+  [xh][button] [styles] button 的皮肤没引：import '@xihan-ui/styles/button.css'，或改引全量的 '@xihan-ui/styles'
+  ```
+
+  两处刻意的取舍：
+
+  - **每个 scope 只探一次。** 探测要读计算样式，逐实例探是真实的强制样式重算；一个 scope 的皮肤
+    在不在场与实例数无关，探一次就够。
+  - **标记落在 `[data-scope='X']` 而不是 root 部件上。** 浮层族的 `content` 被 portal 到 body，
+    不在 root 的子树里，只在 root 上声明的话自定义属性继承不过去，这些部件会误报。
+
+  探测器走 `@xihan-ui/kernel/skin-check` 子路径而不是主入口：它是开发期工具，不该躺在每个消费方都会打包的那条入口里（放主入口会让 kernel 的体积棘轮超 118 B，那条棘轮量的正是整包）。
+
+  新增 `check-skin-markers` 门禁守住 104 份皮肤的标记齐全——漏一份，那个组件就退回静默失效，
+  而且探测器还一声不吭。`pnpm gate` 十九项 → 二十项。
+
+- 59c86fa: 新增 `check-style-entries` 门禁：每份皮肤都必须进得了全量入口、也够得着按需入口。
+
+  `index.css` 的 `@import` 清单是手工维护的，`package.json` 的子路径导出也是。两处任何一处漏了，
+  结果都是静默的：漏进 `index.css`，全量引入的人拿不到那份皮肤，组件渲染成裸元素；
+  漏了子路径导出，按需引入的人根本 import 不到它。今天 109 份皮肤两处齐全，但没有任何东西守着。
+
+  门禁同时把「按需产物的顺序只能由 `index.css` 过滤得来」钉在这里。同一个 `@layer xihan.components`
+  内，等特异性的规则靠源序定胜负；另起一套排序（按字母、按目录读取序）今天看不出差别——
+  当前仅有的 3 处跨 scope 规则在两种排序下相对次序恰好一致——但那正是它危险的地方：
+  将来加进第四处，按需引入的人就会与全量引入的人渲染不同，而且全绿。
+
+  `installation.md` 的「样式的三种接法」如实补上第二种要自己扛的两条风险，并给出体积口径
+  （全量 51 kB gzip，含令牌与 109 份皮肤），建议没有明确体积压力就用全量。
+
+- Updated dependencies [3469066]
+- Updated dependencies [091bbef]
+  - @xihan-ui/tokens@1.0.0-alpha.2
+
 ## 1.0.0-alpha.1
 
 ### Major Changes

package/css/accordion.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='accordion'] {
+    --xh-accordion-skin: 1;
+  }
+
   [data-scope='accordion'][data-part='root'] {
     /* 尺寸档只换这四个私有槽，标题栏从 root 继承它们，换档不必给每个部件各写一条选择器 */
     --xh-_accordion-trigger-h: var(--xh-control-h-md);

package/css/affix.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='affix'] {
+    --xh-affix-skin: 1;
+  }
+
   /* 占位盒就是 content 在常规流里占的那块地方。
      这里不声明 display，也不写高度：吸住时冻结的高度由连接层量好写进内联样式（它量得到，样式表量不到），
      没吸住时高度就该跟着内容走。不给 display，UA 的 [hidden]{display:none} 也仍然压得住 */

package/css/alert.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='alert'] {
+    --xh-alert-skin: 1;
+  }
+
   [data-scope='alert'][data-part='root'] {
     /* 强调色随语气走，底色/描边/图标色都由它推导出来，换语气不必逐条属性各写一遍。
        没写 data-tone 时 --xh-_tone 没被声明，退回原来的 info 蓝 */

package/css/anchor.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='anchor'] {
+    --xh-anchor-skin: 1;
+  }
+
   /* 根节点是 nav 地标，不参与排版：整条目录的布局全在 list 上，
      这里不给 display，UA 的 [hidden]{display:none} 就仍然压得住 */
   [data-scope='anchor'][data-part='root'] {

package/css/avatar-group.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='avatar-group'] {
+    --xh-avatar-group-skin: 1;
+  }
+
   /* 一排叠放的头像：后一枚压在前一枚上。
      组内共用的直径与字号在容器上写一次，沿继承流给每一枚；自己写了档位的那一枚仍按自己的档走 */
   [data-scope='avatar-group'][data-part='root'] {

package/css/avatar.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='avatar'] {
+    --xh-avatar-skin: 1;
+  }
+
   [data-scope='avatar'][data-part='root'] {
     position: relative;
     display: inline-flex;

package/css/back-top.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='back-top'] {
+    --xh-back-top-skin: 1;
+  }
+
   /* 定位壳：钉在视口的尾下角，用逻辑属性，RTL 下自动换到另一侧。
      不声明 display —— 收起态由连接层写 hidden，UA 的 [hidden]{display:none} 得压得住 */
   [data-scope='back-top'][data-part='root'] {

package/css/badge.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='badge'] {
+    --xh-badge-skin: 1;
+  }
+
   [data-scope='badge'][data-part='root'] {
     display: inline-flex;
     align-items: center;

package/css/breadcrumb.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='breadcrumb'] {
+    --xh-breadcrumb-skin: 1;
+  }
+
   /* 根节点是 nav 地标，不参与排版：整条路径的行为全在 list 上，
      这里不给 display，UA 的 [hidden]{display:none} 就仍然压得住 */
   [data-scope='breadcrumb'][data-part='root'] {

package/css/button-group.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='button-group'] {
+    --xh-button-group-skin: 1;
+  }
+
   /* 一组按钮连成一条：段与段之间不留缝，靠共边接上，所以不设 gap。
      排布只能读 data-orientation——role=group 不收 aria-orientation，连接层根本不输出它。
      圆角槽位在容器上先收成 0，组内每段都取得到，两端的圆角再逐段补回来 */

package/css/button.css

@@ -1,4 +1,19 @@
+@layer xihan.motion {
+  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
+     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
+  @keyframes xh-spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+}
+
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='button'] {
+    --xh-button-skin: 1;
+  }
+
   [data-scope='button'][data-part='root'] {
     /* 私有槽位：组件令牌 → 语义令牌两级回退，变体只改这几个槽位 */
     --xh-_bg: var(--xh-button-bg, var(--xh-bg-subtle));

package/css/calendar.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='calendar'] {
+    --xh-calendar-skin: 1;
+  }
+
   [data-scope='calendar'][data-part='root'] {
     display: flex;
     flex-direction: column;

package/css/card.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='card'] {
+    --xh-card-skin: 1;
+  }
+
   [data-scope='card'][data-part='root'] {
     display: flex;
     flex-direction: column;

package/css/carousel.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='carousel'] {
+    --xh-carousel-skin: 1;
+  }
+
   /* 根节点是 region 地标：把上一张 / 视口 / 下一张排成一行，指示点另起一行。
      两端按钮浮在视口上还是排在两侧由作者定，这里只给最朴素的一版排布 */
   [data-scope='carousel'][data-part='root'] {

package/css/cascader.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='cascader'] {
+    --xh-cascader-skin: 1;
+  }
+
   /* 解剖里没有把「触发器 + 清空按钮」裹在一起的 control 部件，一行是靠 flex-wrap 分出来的：
      标签占满整行把后面的挤到下一行，触发器与清空按钮就并排落在同一行上。
      这样作者少写标签、少写清空按钮，剩下的部件也不会塌 */
@@ -277,13 +282,13 @@
 
   [data-scope='cascader'][data-part='content'][data-state='open'] {
     /* 入场横移沿书写方向起始缘：位移量经私有槽供给关键帧，rtl 只翻符号 */
-    --xh-_cascader-slide: -0.25rem;
+    --xh-_cascader-slide: calc(-1 * var(--xh-motion-distance-sm));
 
     animation: xh-cascader-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
   }
 
   [dir='rtl'] [data-scope='cascader'][data-part='content'][data-state='open'] {
-    --xh-_cascader-slide: 0.25rem;
+    --xh-_cascader-slide: var(--xh-motion-distance-sm);
   }
 
   /* 一列：宽度由内容撑出、设下限防塌，高度定死——切换展开路径时浮层不上下跳动，
@@ -561,7 +566,7 @@
   @keyframes xh-cascader-in {
     from {
       opacity: 0;
-      translate: var(--xh-_cascader-slide, -0.25rem) 0;
+      translate: var(--xh-_cascader-slide, calc(-1 * var(--xh-motion-distance-sm))) 0;
     }
 
     to {

package/css/checkbox-group.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='checkbox-group'] {
+    --xh-checkbox-group-skin: 1;
+  }
+
   /* 组容器：label、trigger、条目都是它的直接子节点，排布方式只能读 data-orientation——
      连接层明说了 role=group 不接受 aria-orientation，那个属性它根本没输出 */
   [data-scope='checkbox-group'][data-part='root'] {

package/css/checkbox.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='checkbox'] {
+    --xh-checkbox-skin: 1;
+  }
+
   [data-scope='checkbox'][data-part='root'] {
     /* 尺寸档只换方框边长这一个私有槽，勾的字号按边长的比例跟着走；
        指示器从 root 继承这两个槽，换档不必给每个部件各写一条选择器 */

package/css/clipboard.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='clipboard'] {
+    --xh-clipboard-skin: 1;
+  }
+
   /* 与文本框同一套堆叠：标签一行、输入行一行 */
   [data-scope='clipboard'][data-part='root'] {
     display: inline-flex;

package/css/code-block.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='code-block'] {
+    --xh-code-block-skin: 1;
+  }
+
   /* overflow: hidden 让内部 <pre> 的滚动内容沿圆角收边；不设 display，排布由作者决定 */
   [data-scope='code-block'][data-part='root'] {
     overflow: hidden;

package/css/collapsible.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='collapsible'] {
+    --xh-collapsible-skin: 1;
+  }
+
   /* 根容器自己不排版，这条只声明尺寸档的私有槽：触发按钮从 root 继承它们，
      换档不必给部件各写一条选择器 */
   [data-scope='collapsible'][data-part='root'] {

package/css/color-picker.css

@@ -2,7 +2,7 @@
   @keyframes xh-color-picker-fade-in {
     from {
       opacity: 0;
-      scale: 0.98;
+      scale: var(--xh-motion-scale-enter);
     }
 
     to {
@@ -13,6 +13,11 @@
 }
 
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='color-picker'] {
+    --xh-color-picker-skin: 1;
+  }
+
   /* 定位分工：取色区拇指的两条轴（inset-inline-start / inset-block-start）、
      通道拇指的主轴（inset-inline-start）、浮层坐标、取色区底色、透明度轨道的渐变，
      全都由连接层每帧写进内联样式。这份皮肤一个都不碰：内联优先级高于样式表，

package/css/combobox.css

@@ -1,4 +1,23 @@
+@layer xihan.motion {
+  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
+     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
+  @keyframes xh-fade-in {
+    from {
+      opacity: 0;
+    }
+
+    to {
+      opacity: 1;
+    }
+  }
+}
+
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='combobox'] {
+    --xh-combobox-skin: 1;
+  }
+
   [data-scope='combobox'][data-part='root'] {
     /* 尺寸档只换这五个私有槽，输入行、标题与候选都从 root 继承它们，
        换档不必给每个部件各写一条选择器。浮层在 positioner 里、也是 root 的后代，一并继承 */

package/css/composer.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='composer'] {
+    --xh-composer-skin: 1;
+  }
+
   /* 边框画在 root 上，内部 textarea 无边框；align-items: flex-end 让按钮随输入框长高贴着底边 */
   [data-scope='composer'][data-part='root'] {
     /* 输入与发送按钮共用的控件高度 */

package/css/context-menu.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='context-menu'] {
+    --xh-context-menu-skin: 1;
+  }
+
   /* 根只是把触发区与浮层圈在一起做作用域，不该在作者布局里多插一层盒子 */
   [data-scope='context-menu'][data-part='root'] {
     /* 尺寸档只换这四个私有槽，条目与分组标题都从 root 继承它们，
@@ -102,13 +107,6 @@
     animation: xh-context-menu-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
   }
 
-  /* 关掉动效的用户不该被涨开动画晃一下；这里只管本组件，公共那份不动 */
-  @media (prefers-reduced-motion: reduce) {
-    [data-scope='context-menu'][data-part='content'][data-state='open'] {
-      animation-duration: 0.01ms;
-    }
-  }
-
   [data-scope='context-menu'][data-part='group'] {
     display: flex;
     flex-direction: column;
@@ -282,7 +280,7 @@
   @keyframes xh-context-menu-in {
     from {
       opacity: 0;
-      scale: 0.96;
+      scale: var(--xh-motion-scale-enter);
     }
 
     to {

package/css/countdown.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='countdown'] {
+    --xh-countdown-skin: 1;
+  }
+
   [data-scope='countdown'][data-part='root'] {
     display: inline-block;
     color: var(--xh-countdown-fg, var(--xh-fg-default));

package/css/date-field.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='date-field'] {
+    --xh-date-field-skin: 1;
+  }
+
   /* 与文本框、数字框同一套堆叠：标签一行、分段框一行 */
   [data-scope='date-field'][data-part='root'] {
     /* 尺寸档只换这四个私有槽，标题与分段框都从 root 继承它们，换档不必给每个部件各写一条选择器 */

package/css/date-picker.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='date-picker'] {
+    --xh-date-picker-skin: 1;
+  }
+
   /* 与文本框、分段日期同一套堆叠：标签一行、输入行一行 */
   [data-scope='date-picker'][data-part='root'] {
     display: inline-flex;
@@ -284,7 +289,7 @@
   @keyframes xh-date-picker-in {
     from {
       opacity: 0;
-      translate: 0 -4px;
+      translate: 0 calc(-1 * var(--xh-motion-distance-sm));
     }
 
     to {

package/css/descriptions.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='descriptions'] {
+    --xh-descriptions-skin: 1;
+  }
+
   [data-scope='descriptions'][data-part='root'] {
     /* 一个尺寸档只换这几个私有槽，每一格与格内两段都从根上继承它们，
        换档不必给每个部件各写一条选择器 */

package/css/dialog.css

@@ -1,4 +1,63 @@
+@layer xihan.motion {
+  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
+     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
+  @keyframes xh-fade-in {
+    from {
+      opacity: 0;
+    }
+
+    to {
+      opacity: 1;
+    }
+  }
+
+  @keyframes xh-fade-out {
+    from {
+      opacity: 1;
+    }
+
+    to {
+      opacity: 0;
+    }
+  }
+
+  /* 幅度走令牌，减弱动效时由令牌层归零；位移与缩放用独立属性而非 transform 简写，
+     两者互不覆盖，手势期间写 translate 也不会把 scale 抹掉 */
+  @keyframes xh-dialog-in {
+    from {
+      opacity: 0;
+      translate: 0 var(--xh-motion-distance-md);
+      scale: var(--xh-motion-scale-enter);
+    }
+
+    to {
+      opacity: 1;
+      translate: 0 0;
+      scale: 1;
+    }
+  }
+
+  @keyframes xh-dialog-out {
+    from {
+      opacity: 1;
+      translate: 0 0;
+      scale: 1;
+    }
+
+    to {
+      opacity: 0;
+      translate: 0 var(--xh-motion-distance-md);
+      scale: var(--xh-motion-scale-enter);
+    }
+  }
+}
+
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='dialog'] {
+    --xh-dialog-skin: 1;
+  }
+
   [data-scope='dialog'][data-part='backdrop'] {
     position: fixed;
     inset: 0;
@@ -10,8 +69,9 @@
     animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
   }
 
+  /* 退场补 forwards：动画播完到宿主真正卸载之间还有一帧，不定住终态遮罩会闪回全黑 */
   [data-scope='dialog'][data-part='backdrop'][data-state='closed'] {
-    animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit);
+    animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   [data-scope='dialog'][data-part='positioner'] {
@@ -48,12 +108,13 @@
     box-shadow: var(--xh-dialog-shadow, var(--xh-elevation-3));
   }
 
-  /* 收起态：connect 会给 content 打 hidden，但上面那条 display 会盖掉 UA 的
-     [hidden]{display:none}。meta 里 positioner 并非必需部件，按最小合规结构
-     （只有 trigger + content）写时，没有这一条收起的对话框就一直摊在页面上。 */
-  [data-scope='dialog'][data-part='content'][hidden] {
-    display: none;
-  }
+  /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 drawer 一致：
+     收起态连接层会给 content 打 hidden，而上面那条 display: flex 正是要盖掉 UA 的
+     [hidden]{display:none}——退场动画得先能播。presence 读的是 content 的 animationName，
+     读到才申领租约、等 animationend 才卸载；一旦 display: none，元素不生成盒子、
+     动画根本不启动，探测器直接放弃租约，退场动画一帧都播不出来。
+     真正的收起由适配器兜住：Vue 卸载整棵，WC 写内联 style.display。
+     其余声明了 display 的角色节点仍补 [hidden]，那几处没有退场动画。 */
 
   /* —— 尺寸 —— */
   /* 只有最大宽度分档；中间档不写规则，缺省即中档。
@@ -70,13 +131,12 @@
     outline: none;
   }
 
-  /* 入场用 @starting-style 只驱动动画名切换；退场由 presence 保留 DOM 后播放 */
   [data-scope='dialog'][data-part='content'][data-state='open'] {
     animation: xh-dialog-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
   }
 
   [data-scope='dialog'][data-part='content'][data-state='closed'] {
-    animation: xh-dialog-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit);
+    animation: xh-dialog-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   [data-scope='dialog'][data-part='title'] {

package/css/drawer.css

@@ -1,4 +1,26 @@
 @layer xihan.motion {
+  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
+     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
+  @keyframes xh-fade-in {
+    from {
+      opacity: 0;
+    }
+
+    to {
+      opacity: 1;
+    }
+  }
+
+  @keyframes xh-fade-out {
+    from {
+      opacity: 1;
+    }
+
+    to {
+      opacity: 0;
+    }
+  }
+
   /* 四条边各一对滑入/滑出。位移量用 translate 的百分比，参照的是面板自己的边框盒，
      所以不管 --xh-drawer-size 被改成多少，"正好推到视口外"这件事都成立。
 
@@ -85,15 +107,14 @@
       translate: 0 var(--xh-_drawer-shift-block, 100%);
     }
   }
-
-  @media (prefers-reduced-motion: reduce) {
-    [data-scope='drawer'][data-part] {
-      animation-duration: 0.01ms !important;
-    }
-  }
 }
 
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='drawer'] {
+    --xh-drawer-skin: 1;
+  }
+
   /* root 留在页面原地，只是 data-side / data-state 的落点，不该凭空多出一层盒子把
      trigger 从作者的 flex / grid 行里挤出去，故 display: contents。 */
   [data-scope='drawer'][data-part='root'] {
@@ -218,9 +239,9 @@
   /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致。
      收起态连接层会给 content 打 hidden，而上面这条 display: flex 正是要盖掉
      UA 的 [hidden]{display:none}——退场动画得先能播：
-     Vue 侧 presence 读的是 content 的 animationName，读到就申领租约、等 animationend
-     才卸载；一旦 display: none，动画根本不会启动，animationend 永不到达，
-     租约挂死，面板就永久留在 DOM 里（每开合一次多一份）。
+     presence 读的是 content 的 animationName，读到就申领租约、等 animationend 才卸载；
+     一旦 display: none，元素不生成盒子、动画根本不启动，退场探测器会直接放弃申领
+     （否则就要等一个永不到来的 animationend），面板不播动画就地卸载。
      真正的收起两个适配器各自兜住了：Vue 卸载整棵，WC 写内联 style.display。
      其余声明了 display 的角色节点仍补了 [hidden]，那几处没有退场动画，作者手写 hidden 要生效。 */