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

package/css/hover-card.css

@@ -1,4 +1,36 @@
+@layer xihan.motion {
+  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
+     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
+  @keyframes xh-pop-in {
+    from {
+      opacity: 0;
+      scale: var(--xh-motion-scale-enter);
+    }
+
+    to {
+      opacity: 1;
+      scale: 1;
+    }
+  }
+  @keyframes xh-pop-out {
+    from {
+      opacity: 1;
+      scale: 1;
+    }
+
+    to {
+      opacity: 0;
+      scale: var(--xh-motion-scale-enter);
+    }
+  }
+}
+
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='hover-card'] {
+    --xh-hover-card-skin: 1;
+  }
+
   /* 根节点只把 trigger 与浮层收在一处，不参与定位（坐标系仍由祖先的定位上下文决定） */
   [data-scope='hover-card'][data-part='root'] {
     display: inline-block;
@@ -31,8 +63,12 @@
 
   /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
   [data-scope='hover-card'][data-part='positioner'] {
+    /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，内容层继承它限高；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时不额外限高 */
+    --xh-_hover-card-available-h: 100vh;
+
     position: fixed;
-    z-index: var(--xh-layer-popover);
+    z-index: var(--xh-hover-card-layer, var(--xh-layer-popover));
     /* 空壳不吃指针：trigger 与 content 之间那段间隙要能点得穿，
        指针穿行的判定全靠 content 自己的进出事件 */
     pointer-events: none;
@@ -58,22 +94,24 @@
     gap: var(--xh-hover-card-gap, var(--xh-space-2));
     inline-size: max-content;
     max-inline-size: var(--xh-hover-card-max-w, var(--xh-_hover-card-max-w));
+    /* 内容由作者给，长度不可预知：不限高就整块伸出视口且滚不到 */
+    max-block-size: min(var(--xh-hover-card-max-h, var(--xh-overlay-max-h)), var(--xh-_hover-card-available-h));
+    overflow-y: auto;
     padding-block: var(--xh-hover-card-py, var(--xh-_hover-card-py));
     padding-inline: var(--xh-hover-card-px, var(--xh-_hover-card-px));
     border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-border-default));
     border-radius: var(--xh-hover-card-radius, var(--xh-shape-surface));
     background: var(--xh-hover-card-bg, var(--xh-bg-surface));
     color: var(--xh-hover-card-fg, var(--xh-fg-default));
-    font-size: var(--xh-hover-card-font-size, var(--xh-text-body-size));
-    line-height: var(--xh-leading-normal);
-    box-shadow: var(--xh-hover-card-shadow, var(--xh-elevation-2));
+    box-shadow: var(--xh-hover-card-shadow, var(--xh-elevation-floating));
     pointer-events: auto;
   }
 
-  /* display 会盖掉 hidden 属性的 UA 规则，收起态显式让位 */
-  [data-scope='hover-card'][data-part='content'][hidden] {
-    display: none;
-  }
+  /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
+     收起态连接层会给 content 打 hidden，而上面那条 display 正是要盖掉 UA 的
+     [hidden]{display:none}——退场动画得先能播。presence 读的是 content 的 animationName，
+     真正的收起由宿主在退场结束后落成内联 display:none（Vue 那边直接不渲染）。
+     其余声明了 display 的角色节点仍补 [hidden]，那几处没有退场动画。 */
 
   /* 卡片是可编程聚焦的容器（tabindex=-1），焦点环留给里面真正的可聚焦元素 */
   [data-scope='hover-card'][data-part='content']:focus-visible {
@@ -81,7 +119,13 @@
   }
 
   [data-scope='hover-card'][data-part='content'][data-state='open'] {
-    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
+     免得动画结束到真收起之间闪一下原样 */
+  [data-scope='hover-card'][data-part='content'][data-state='closed'] {
+    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   /* —— 尺寸 —— */
@@ -99,52 +143,16 @@
     --xh-_hover-card-max-w: var(--xh-overlay-max-w-lg);
   }
 
-  /* 箭头是旋转 45° 的方块，只保留朝向锚点那两条边的描边；
+  /* 箭头的底色与描边色，几何在 overlay-arrow.css。
      交叉轴落点由定位引擎经内联自定义属性写进来，没给时退回居中 */
   [data-scope='hover-card'][data-part='arrow'] {
-    --xh-_hover-card-arrow-size: var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size));
     --xh-_hover-card-arrow-x: 50%;
     --xh-_hover-card-arrow-y: 50%;
+    --xh-_overlay-arrow-size: var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size));
+    --xh-_overlay-arrow-x: var(--xh-_hover-card-arrow-x);
+    --xh-_overlay-arrow-y: var(--xh-_hover-card-arrow-y);
 
-    position: absolute;
-    inline-size: var(--xh-_hover-card-arrow-size);
-    block-size: var(--xh-_hover-card-arrow-size);
-    border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-border-default));
     background: var(--xh-hover-card-bg, var(--xh-bg-surface));
-    rotate: 45deg;
-  }
-
-  [data-scope='hover-card'][data-part='arrow'][data-placement^='bottom'] {
-    inset-block-start: calc(var(--xh-_hover-card-arrow-size) / -2);
-    inset-inline-start: calc(var(--xh-_hover-card-arrow-x) - var(--xh-_hover-card-arrow-size) / 2);
-    border-block-end: 0;
-    border-inline-end: 0;
-  }
-
-  [data-scope='hover-card'][data-part='arrow'][data-placement^='top'] {
-    inset-block-end: calc(var(--xh-_hover-card-arrow-size) / -2);
-    inset-inline-start: calc(var(--xh-_hover-card-arrow-x) - var(--xh-_hover-card-arrow-size) / 2);
-    border-block-start: 0;
-    border-inline-start: 0;
-  }
-
-  [data-scope='hover-card'][data-part='arrow'][data-placement^='right'] {
-    inset-inline-start: calc(var(--xh-_hover-card-arrow-size) / -2);
-    inset-block-start: calc(var(--xh-_hover-card-arrow-y) - var(--xh-_hover-card-arrow-size) / 2);
-    border-block-start: 0;
-    border-inline-end: 0;
-  }
-
-  [data-scope='hover-card'][data-part='arrow'][data-placement^='left'] {
-    inset-inline-end: calc(var(--xh-_hover-card-arrow-size) / -2);
-    inset-block-start: calc(var(--xh-_hover-card-arrow-y) - var(--xh-_hover-card-arrow-size) / 2);
-    border-block-end: 0;
-    border-inline-start: 0;
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    [data-scope='hover-card'][data-part='content'] {
-      animation-duration: 0.01ms !important;
-    }
+    border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-border-default));
   }
 }

package/css/icon-wrapper.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='icon-wrapper'] {
+    --xh-icon-wrapper-skin: 1;
+  }
+
   /* 定直径的图标底座：图元在正中，底色、描边与形状由三轴决定。
      直径与图元直径分两个槽位，底座换档时里面的图元跟着一起换 */
   [data-scope='icon-wrapper'][data-part='root'] {

package/css/icon.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='icon'] {
+    --xh-icon-skin: 1;
+  }
+
   /*
    * 根 <svg>。直径、描边粗细、行内位置都由这里给，记录只带几何。
    * 不写 fill / stroke：记录里那两条呈现属性取 currentColor，改这里会把

package/css/image-cropper.css

@@ -0,0 +1,231 @@
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='image-cropper'] {
+    --xh-image-cropper-skin: 1;
+  }
+
+  /* 定位分工：裁切框在视口里的 left / top / width / height，以及图片与裁切框的
+     transform，由连接层每帧写进内联样式——那四个数是图片像素换算出来的百分比，
+     只有连接层算得出来。这份皮肤一个都不碰，写了不但是死声明，还会跟内联值抢位置。
+
+     私有槽两个，都挂在 root 上靠继承发下去：
+     handle-size 是把手的边长，zoom 是当前缩放倍率——裁切框整体被 scale 放大，
+     把手与描边要按倍率反向缩回去，否则放到 3 倍时把手也变成三倍大、描边变成三像素粗。 */
+  [data-scope='image-cropper'][data-part='root'] {
+    --xh-_image-cropper-handle-size: var(--xh-image-cropper-handle-size, var(--xh-control-indicator-size));
+    --xh-_image-cropper-zoom: 1;
+
+    position: relative;
+    display: block;
+    inline-size: var(--xh-image-cropper-w, 100%);
+  }
+
+  /* 量坐标的那个盒子。里面装的是图片像素坐标，不是文字：裁切框与把手的落点一律写物理属性，
+     不依赖这里的文字方向。overflow 收口：放大后的图片与遮罩都靠它裁掉。 */
+  [data-scope='image-cropper'][data-part='viewport'] {
+    position: relative;
+    display: block;
+    overflow: hidden;
+    border-radius: var(--xh-image-cropper-radius, var(--xh-shape-surface));
+    background: var(--xh-image-cropper-bg, var(--xh-bg-muted));
+    user-select: none;
+  }
+
+  /* 图片铺满视口、高度自适应：视口的高度因此由图片撑出来，
+     裁切框的百分比坐标才与图片的像素一一对应。 */
+  [data-scope='image-cropper'][data-part='image'] {
+    display: block;
+    inline-size: 100%;
+    block-size: auto;
+  }
+
+  /* 裁切框。遮罩用一圈超大的实心投影把框外压暗——不必再摆四块遮罩节点，
+     圆形裁切时投影也自动跟着圆角走。描边按倍率缩回去，放大时仍是一根细线。 */
+  [data-scope='image-cropper'][data-part='crop-area'] {
+    position: absolute;
+    box-sizing: border-box;
+    border-style: solid;
+    border-width: calc(var(--xh-stroke-thin) / var(--xh-_image-cropper-zoom));
+    border-color: var(--xh-image-cropper-crop-border, var(--xh-bg-surface));
+    box-shadow: 0 0 0 9999px var(--xh-image-cropper-mask, var(--xh-bg-overlay));
+    cursor: move;
+  }
+
+  /* 圆形裁切的这一档只能写 50%：shape 那四档给的是固定长度，
+     裁切框的宽高由数据决定、两边通常不等长，固定长度画出来是胶囊不是椭圆。 */
+  [data-scope='image-cropper'][data-part='crop-area'][data-shape='round'] {
+    border-radius: 50%;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-area'][data-dragging] {
+    cursor: grabbing;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-area'][data-readonly] {
+    cursor: default;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-area'][data-disabled] {
+    cursor: not-allowed;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-area']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* 三分构图参考线：两条竖线、两条横线，落点写死在三分处，不占节点、不吃指针。
+     停靠点逐条写全而不用 repeating-：重复单元从 0 起算会在框的两条边缘上各多画一根，
+     那两根与裁切框的描边叠在一起，看着像描边加粗了一倍。
+     线宽跟着裁切框的倍率缩回去，与描边同一口径。
+     圆形裁切时参考线没有意义，收起来。 */
+  [data-scope='image-cropper'][data-part='grid'] {
+    --xh-_image-cropper-grid-w: calc(var(--xh-stroke-thin) / var(--xh-_image-cropper-zoom));
+
+    position: absolute;
+    inset: 0;
+    background-image:
+      linear-gradient(
+        to right,
+        transparent 0 33.3333%,
+        var(--xh-image-cropper-grid-line, var(--xh-border-subtle)) 33.3333% calc(33.3333% + var(--xh-_image-cropper-grid-w)),
+        transparent calc(33.3333% + var(--xh-_image-cropper-grid-w)) 66.6667%,
+        var(--xh-image-cropper-grid-line, var(--xh-border-subtle)) 66.6667% calc(66.6667% + var(--xh-_image-cropper-grid-w)),
+        transparent calc(66.6667% + var(--xh-_image-cropper-grid-w)) 100%
+      ),
+      linear-gradient(
+        to bottom,
+        transparent 0 33.3333%,
+        var(--xh-image-cropper-grid-line, var(--xh-border-subtle)) 33.3333% calc(33.3333% + var(--xh-_image-cropper-grid-w)),
+        transparent calc(33.3333% + var(--xh-_image-cropper-grid-w)) 66.6667%,
+        var(--xh-image-cropper-grid-line, var(--xh-border-subtle)) 66.6667% calc(66.6667% + var(--xh-_image-cropper-grid-w)),
+        transparent calc(66.6667% + var(--xh-_image-cropper-grid-w)) 100%
+      );
+    pointer-events: none;
+  }
+
+  [data-scope='image-cropper'][data-part='grid'][data-shape='round'] {
+    background-image: none;
+  }
+
+  /* 把手钉在裁切框的角与边上。落点写物理 left / top：裁切框的坐标是图片像素，
+     连接层写进内联样式的也是物理 left / top，把手跟着走才不会与框错开一侧。
+     translate 把方块的中心挪到点上；scale 按倍率缩回去，缩放时把手看着大小不变。 */
+  [data-scope='image-cropper'][data-part='crop-handle'] {
+    position: absolute;
+    display: block;
+    box-sizing: border-box;
+    border-style: solid;
+    border-width: calc(var(--xh-stroke-thin) / var(--xh-_image-cropper-zoom));
+    border-color: var(--xh-image-cropper-handle-border, var(--xh-border-strong));
+    border-radius: var(--xh-image-cropper-handle-radius, var(--xh-shape-inset));
+    background: var(--xh-image-cropper-handle-bg, var(--xh-bg-surface));
+    inline-size: var(--xh-_image-cropper-handle-size);
+    block-size: var(--xh-_image-cropper-handle-size);
+    translate: -50% -50%;
+    scale: calc(1 / var(--xh-_image-cropper-zoom));
+  }
+
+  /* 看得见的方块比手指小：另铺一层不可见的命中区，把它撑到最小可点尺寸。
+     inset 取负值即向四面外扩，方块本身更大时这个值转正、命中区仍是方块那么大。 */
+  [data-scope='image-cropper'][data-part='crop-handle']::before {
+    position: absolute;
+    inset: calc((var(--xh-_image-cropper-handle-size) - var(--xh-control-action-size)) / 2);
+    content: '';
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-resizing] {
+    background: var(--xh-image-cropper-handle-bg-resizing, var(--xh-bg-brand));
+  }
+
+  /* —— 八个方位：落点 + 光标 —— */
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='nw'] {
+    top: 0;
+    /* stylelint-disable-next-line property-disallowed-list -- 裁切框的坐标是图片像素，落点跟着物理方向走 */
+    left: 0;
+    cursor: nwse-resize;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='n'] {
+    top: 0;
+    /* stylelint-disable-next-line property-disallowed-list -- 同上 */
+    left: 50%;
+    cursor: ns-resize;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='ne'] {
+    top: 0;
+    /* stylelint-disable-next-line property-disallowed-list -- 同上 */
+    left: 100%;
+    cursor: nesw-resize;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='e'] {
+    top: 50%;
+    /* stylelint-disable-next-line property-disallowed-list -- 同上 */
+    left: 100%;
+    cursor: ew-resize;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='se'] {
+    top: 100%;
+    /* stylelint-disable-next-line property-disallowed-list -- 同上 */
+    left: 100%;
+    cursor: nwse-resize;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='s'] {
+    top: 100%;
+    /* stylelint-disable-next-line property-disallowed-list -- 同上 */
+    left: 50%;
+    cursor: ns-resize;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='sw'] {
+    top: 100%;
+    /* stylelint-disable-next-line property-disallowed-list -- 同上 */
+    left: 0;
+    cursor: nesw-resize;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='w'] {
+    top: 50%;
+    /* stylelint-disable-next-line property-disallowed-list -- 同上 */
+    left: 0;
+    cursor: ew-resize;
+  }
+
+  /* 只读与禁用的光标排在八个方位之后：那八条每条都写了 cursor，特异性又完全相同，
+     排在前面会被逐条盖掉，整条规则等于没写。 */
+  [data-scope='image-cropper'][data-part='crop-handle'][data-readonly] {
+    cursor: default;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-disabled] {
+    cursor: not-allowed;
+  }
+
+  /* 禁用的整体压暗只做一次，落在最外层：视口、裁切框、把手各自再叠一层会越叠越黑。
+     这里只用 opacity、不换前景色：框里是图像，没有文字可换。 */
+  [data-scope='image-cropper'][data-part='root'][data-disabled] {
+    cursor: not-allowed;
+    opacity: var(--xh-state-disabled-opacity);
+  }
+
+  /* hidden-input 是 type=hidden 的原生输入，浏览器本就不渲染它，
+     这里一条声明都不给：给了 display / 尺寸反而会把它拽回布局里撑出一块空白。 */
+
+  /* display 会盖掉 UA 的 [hidden]{display:none}，凡是被赋了 display 的角色节点都要显式让位。
+     这条必须排在全部 display 声明之后。 */
+  [data-scope='image-cropper'][data-part='root'][hidden],
+  [data-scope='image-cropper'][data-part='viewport'][hidden],
+  [data-scope='image-cropper'][data-part='image'][hidden],
+  [data-scope='image-cropper'][data-part='crop-handle'][hidden] {
+    display: none;
+  }
+}

package/css/image-viewer.css

@@ -1,8 +1,37 @@
+@layer xihan.motion {
+  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
+     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
+  @keyframes xh-fade-in {
+    from {
+      opacity: 0;
+    }
+
+    to {
+      opacity: 1;
+    }
+  }
+
+  @keyframes xh-fade-out {
+    from {
+      opacity: 1;
+    }
+
+    to {
+      opacity: 0;
+    }
+  }
+}
+
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='image-viewer'] {
+    --xh-image-viewer-skin: 1;
+  }
+
   [data-scope='image-viewer'][data-part='backdrop'] {
     position: fixed;
     inset: 0;
-    z-index: var(--xh-layer-modal);
+    z-index: var(--xh-image-viewer-backdrop-layer, var(--xh-layer-modal));
     /* 看片要压住页面底色，遮罩比普通对话框更深 */
     background: var(--xh-image-viewer-backdrop-bg, color-mix(in oklab, var(--xh-color-neutral-950) 78%, transparent));
   }
@@ -12,19 +41,22 @@
   }
 
   [data-scope='image-viewer'][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='image-viewer'][data-part='positioner'] {
     position: fixed;
     inset: 0;
-    z-index: var(--xh-layer-modal);
+    z-index: var(--xh-image-viewer-layer, var(--xh-layer-modal));
     display: flex;
     align-items: center;
     justify-content: center;
   }
 
   [data-scope='image-viewer'][data-part='content'] {
+    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-image-viewer-icon-size, var(--xh-glyph-size-text));
+
     position: relative;
     inline-size: 100%;
     block-size: 100%;
@@ -41,11 +73,7 @@
   }
 
   [data-scope='image-viewer'][data-part='content'][data-state='closed'] {
-    animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit);
-  }
-
-  [data-scope='image-viewer'][data-part='content'][hidden] {
-    display: none;
+    animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   [data-scope='image-viewer'][data-part='viewport'] {
@@ -69,7 +97,7 @@
     max-block-size: 85%;
     user-select: none;
     /* 变换是内联 style 写的，只给缩放旋转一点缓动；拖拽平移要跟手，不缓 */
-    transition: transform var(--xh-duration-fast) var(--xh-ease-out);
+    transition: transform var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   [data-scope='image-viewer'][data-part='image'][data-panning] {
@@ -80,8 +108,7 @@
   [data-scope='image-viewer'][data-part='toolbar'],
   [data-scope='image-viewer'][data-part='counter'],
   [data-scope='image-viewer'][data-part='prev-trigger'],
-  [data-scope='image-viewer'][data-part='next-trigger'],
-  [data-scope='image-viewer'][data-part='close-trigger'] {
+  [data-scope='image-viewer'][data-part='next-trigger'] {
     position: absolute;
     z-index: 1;
     background: var(--xh-image-viewer-chrome-bg, color-mix(in oklab, var(--xh-color-neutral-950) 55%, transparent));
@@ -121,12 +148,11 @@
     inset-inline-start: 50%;
     translate: -50% 0;
     padding: var(--xh-space-1) var(--xh-space-3);
-    font-size: var(--xh-font-size-sm);
+    font-size: var(--xh-text-secondary-size);
   }
 
   [data-scope='image-viewer'][data-part='prev-trigger'],
-  [data-scope='image-viewer'][data-part='next-trigger'],
-  [data-scope='image-viewer'][data-part='close-trigger'] {
+  [data-scope='image-viewer'][data-part='next-trigger'] {
     display: inline-flex;
     align-items: center;
     justify-content: center;
@@ -148,9 +174,39 @@
     translate: 0 -50%;
   }
 
+  /* 右上角的关闭钮：与翻页钮同底同高，但圆角走控件档，按下有缩放 */
   [data-scope='image-viewer'][data-part='close-trigger'] {
+    position: absolute;
+    z-index: 1;
     inset-block-start: var(--xh-space-6);
     inset-inline-end: var(--xh-space-6);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-image-viewer-close-size, var(--xh-control-h-lg));
+    block-size: var(--xh-image-viewer-close-size, var(--xh-control-h-lg));
+    border: none;
+    border-radius: var(--xh-image-viewer-close-radius, var(--xh-shape-control));
+    background: var(--xh-image-viewer-chrome-bg, color-mix(in oklab, var(--xh-color-neutral-950) 55%, transparent));
+    color: inherit;
+    font-size: var(--xh-glyph-size-md);
+    cursor: pointer;
+    transition:
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      scale var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='image-viewer'][data-part='close-trigger'][hidden] {
+    display: none;
+  }
+
+  [data-scope='image-viewer'][data-part='close-trigger']:hover:not(:disabled) {
+    background: var(--xh-image-viewer-close-bg-hover, color-mix(in oklab, var(--xh-color-neutral-950) 70%, transparent));
+  }
+
+  [data-scope='image-viewer'][data-part='close-trigger']:active {
+    background: var(--xh-image-viewer-close-bg-active, color-mix(in oklab, var(--xh-color-neutral-950) 80%, transparent));
+    scale: var(--xh-motion-scale-press);
   }
 
   [data-scope='image-viewer'] button[data-part]:focus-visible {
@@ -163,14 +219,103 @@
     cursor: not-allowed;
   }
 
-  @media (prefers-reduced-motion: reduce) {
-    [data-scope='image-viewer'][data-part='backdrop'],
-    [data-scope='image-viewer'][data-part='content'] {
-      animation-duration: 0.01ms;
-    }
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
+  [data-scope='image-viewer'][data-part='zoom-in-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-zoom-in) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-zoom-in) center / contain no-repeat;
+  }
 
-    [data-scope='image-viewer'][data-part='image'] {
-      transition: none;
-    }
+  [data-scope='image-viewer'][data-part='zoom-out-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-zoom-out) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-zoom-out) center / contain no-repeat;
+  }
+
+  [data-scope='image-viewer'][data-part='rotate-left-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-rotate-left) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-rotate-left) center / contain no-repeat;
+  }
+
+  [data-scope='image-viewer'][data-part='rotate-right-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-rotate-right) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-rotate-right) center / contain no-repeat;
+  }
+
+  [data-scope='image-viewer'][data-part='flip-horizontal-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-flip-horizontal) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-flip-horizontal) center / contain no-repeat;
+  }
+
+  [data-scope='image-viewer'][data-part='flip-vertical-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-flip-vertical) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-flip-vertical) center / contain no-repeat;
+  }
+
+  [data-scope='image-viewer'][data-part='prev-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-chevron-left) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-left) center / contain no-repeat;
+  }
+
+  [data-scope='image-viewer'][data-part='next-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-chevron-right) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-right) center / contain no-repeat;
+  }
+
+  [data-scope='image-viewer'][data-part='close-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-close) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-close) center / contain no-repeat;
   }
 }