@xihan-ui/styles 1.0.0 → 2.0.0

package/css/image-cropper.css

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 image cropper 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='image-cropper'] {
@@ -26,7 +33,7 @@
     position: relative;
     display: block;
     overflow: hidden;
-    border-radius: var(--xh-image-cropper-radius, var(--xh-shape-surface));
+    border-radius: var(--xh-image-cropper-viewport-radius, var(--xh-shape-surface));
     background: var(--xh-image-cropper-bg, var(--xh-bg-muted));
     user-select: none;
   }
@@ -42,6 +49,8 @@
   /* 裁切框。遮罩用一圈超大的实心投影把框外压暗——不必再摆四块遮罩节点，
      圆形裁切时投影也自动跟着圆角走。描边按倍率缩回去，放大时仍是一根细线。 */
   [data-scope='image-cropper'][data-part='crop-area'] {
+    --xh-_image-cropper-corner-radius: var(--xh-shape-control);
+
     position: absolute;
     box-sizing: border-box;
     border-style: solid;
@@ -51,30 +60,22 @@
     cursor: move;
   }
 
-  /* 圆形裁切的这一档只能写 50%：shape 那四档给的是固定长度，
-     裁切框的宽高由数据决定、两边通常不等长，固定长度画出来是胶囊不是椭圆。 */
+  /* 圆形裁切取 circle 档（50%）：shape 的固定长度档画出来是胶囊不是椭圆，
+     裁切框的宽高由数据决定、两边通常不等长，只有百分比才随框变成椭圆；圆角只能来自语义形状令牌（§6.3） */
   [data-scope='image-cropper'][data-part='crop-area'][data-shape='round'] {
-    border-radius: 50%;
+    --xh-_image-cropper-corner-radius: var(--xh-shape-circle);
+
+    border-radius: var(--xh-image-cropper-crop-area-radius, var(--xh-shape-circle));
   }
 
   [data-scope='image-cropper'][data-part='crop-area'][data-dragging] {
     cursor: grabbing;
   }
 
-  [data-scope='image-cropper'][data-part='crop-area'][data-readonly] {
+  [data-scope='image-cropper'][data-part='crop-area'][data-readonly]:not([data-disabled]) {
     cursor: default;
   }
 
-  [data-scope='image-cropper'][data-part='crop-area'][data-disabled] {
-    cursor: not-allowed;
-  }
-
-  /* 环往内收：裁切框长在视口里，视口那层 overflow: hidden 会把画在外沿的环裁掉 */
-  [data-scope='image-cropper'][data-part='crop-area']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: calc(-1 * var(--xh-ring-width));
-  }
-
   /* 三分构图参考线：两条竖线、两条横线，落点写死在三分处，不占节点、不吃指针。
      停靠点逐条写全而不用 repeating-：重复单元从 0 起算会在框的两条边缘上各多画一根，
      那两根与裁切框的描边叠在一起，看着像描边加粗了一倍。
@@ -109,24 +110,33 @@
     background-image: none;
   }
 
-  /* 把手钉在裁切框的角与边上。落点写物理 left / top：裁切框的坐标是图片像素，
-     连接层写进内联样式的也是物理 left / top，把手跟着走才不会与框错开一侧。
-     translate 把方块的中心挪到点上；scale 按倍率缩回去，缩放时把手看着大小不变。 */
+  /* 把手的命中区仍以裁切框边界为中心，视觉短条与折角贴住边框并向框内绘制。 */
   [data-scope='image-cropper'][data-part='crop-handle'] {
+    --xh-_image-cropper-handle-color: var(--xh-image-cropper-handle-bg, var(--xh-bg-surface));
+
     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));
+    border: 0;
+    background: transparent;
     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));
   }
 
+  [data-scope='image-cropper'][data-part='crop-handle']::after {
+    content: '';
+    position: absolute;
+    box-sizing: border-box;
+    border-radius: var(--xh-image-cropper-handle-radius, var(--xh-shape-pill));
+    background: var(--xh-_image-cropper-handle-color);
+    pointer-events: none;
+    transition:
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
   /* 看得见的方块比手指小：另铺一层不可见的命中区，把它撑到最小可点尺寸。
      inset 取负值即向四面外扩，方块本身更大时这个值转正、命中区仍是方块那么大。 */
   [data-scope='image-cropper'][data-part='crop-handle']::before {
@@ -135,14 +145,19 @@
     content: '';
   }
 
-  /* 与裁切框同一口径：把手也在视口的 overflow: hidden 里，环画在外沿会被裁掉 */
-  [data-scope='image-cropper'][data-part='crop-handle']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: calc(-1 * var(--xh-ring-width));
+  /* 把手静息是白面（bg-surface），悬停从同一语义面派生一档（§7.2 第 8 条），不切到品牌淡底；拖动中才是品牌实心 */
+  [data-scope='image-cropper'][data-part='crop-handle']:hover:not([data-disabled], [data-readonly]) {
+    --xh-_image-cropper-handle-color: var(--xh-image-cropper-handle-bg-hover, var(--xh-bg-subtle));
   }
 
   [data-scope='image-cropper'][data-part='crop-handle'][data-resizing] {
-    background: var(--xh-image-cropper-handle-bg-resizing, var(--xh-bg-brand));
+    --xh-_image-cropper-handle-color: var(--xh-image-cropper-handle-bg-resizing, var(--xh-bg-brand));
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle']:focus-visible {
+    --xh-_image-cropper-handle-color: var(--xh-ring-focus);
+
+    outline: none;
   }
 
   /* —— 八个方位：落点 + 光标 —— */
@@ -202,6 +217,96 @@
     cursor: ew-resize;
   }
 
+  /* stylelint-disable property-disallowed-list -- 裁切框的八向位置使用图片物理坐标，内部标记必须朝对应物理方向内收 */
+  [data-scope='image-cropper'][data-part='crop-handle']:is([data-position='n'], [data-position='s'])::after {
+    left: 50%;
+    inline-size: var(--xh-image-cropper-handle-length, var(--xh-space-8));
+    block-size: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+    translate: -50% 0;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='n']::after {
+    top: 50%;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='s']::after {
+    bottom: 50%;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle']:is([data-position='e'], [data-position='w'])::after {
+    top: 50%;
+    inline-size: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+    block-size: var(--xh-image-cropper-handle-length, var(--xh-space-8));
+    translate: 0 -50%;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='e']::after {
+    right: 50%;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='w']::after {
+    left: 50%;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='nw'] {
+    border-start-start-radius: var(--xh-_image-cropper-corner-radius);
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='ne'] {
+    border-start-end-radius: var(--xh-_image-cropper-corner-radius);
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='sw'] {
+    border-end-start-radius: var(--xh-_image-cropper-corner-radius);
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='se'] {
+    border-end-end-radius: var(--xh-_image-cropper-corner-radius);
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle']:is(
+    [data-position='nw'],
+    [data-position='ne'],
+    [data-position='sw'],
+    [data-position='se']
+  )::after {
+    inline-size: calc(var(--xh-_image-cropper-handle-size) / 2);
+    block-size: calc(var(--xh-_image-cropper-handle-size) / 2);
+    border: 0 solid var(--xh-image-cropper-handle-border, var(--xh-_image-cropper-handle-color));
+    border-radius: inherit;
+    background: transparent;
+    outline: none;
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='nw']::after {
+    right: 0;
+    bottom: 0;
+    border-block-start-width: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+    border-inline-start-width: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='ne']::after {
+    bottom: 0;
+    left: 0;
+    border-block-start-width: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+    border-inline-end-width: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='sw']::after {
+    top: 0;
+    right: 0;
+    border-block-end-width: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+    border-inline-start-width: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+  }
+
+  [data-scope='image-cropper'][data-part='crop-handle'][data-position='se']::after {
+    top: 0;
+    left: 0;
+    border-block-end-width: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+    border-inline-end-width: var(--xh-image-cropper-handle-thickness, var(--xh-stroke-strong));
+  }
+  /* stylelint-enable property-disallowed-list */
+
   /* 只读与禁用的光标排在八个方位之后：那八条每条都写了 cursor，特异性又完全相同，
      排在前面会被逐条盖掉，整条规则等于没写。 */
   [data-scope='image-cropper'][data-part='crop-handle'][data-readonly] {
@@ -212,10 +317,19 @@
     cursor: not-allowed;
   }
 
+  /* 两条控制轴用原生 range：拇指与轨道交给平台画，这里只给横向铺满与品牌色。
+     不写 block-size：原生 range 的高度由 UA 与拇指尺寸定，写死会把拇指切掉一截。 */
+  [data-scope='image-cropper'][data-part='zoom-slider'],
+  [data-scope='image-cropper'][data-part='rotate-slider'] {
+    inline-size: var(--xh-image-cropper-slider-w, 100%);
+    /* 原生 range 自带左右各一段外边距，与铺满的宽度叠在一起就把这两条轴顶出容器 */
+    margin-inline: 0;
+    accent-color: var(--xh-image-cropper-slider-accent, var(--xh-bg-brand));
+  }
+
   /* 禁用的整体压暗只做一次，落在最外层：视口、裁切框、把手各自再叠一层会越叠越黑。
      这里只用 opacity、不换前景色：框里是图像，没有文字可换。 */
   [data-scope='image-cropper'][data-part='root'][data-disabled] {
-    cursor: not-allowed;
     opacity: var(--xh-state-disabled-opacity);
   }
 

package/css/image-viewer.css

@@ -1,26 +1,14 @@
-@layer xihan.motion {
-  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
-     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
-  @keyframes xh-fade-in {
-    from {
-      opacity: 0;
-    }
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
 
-    to {
-      opacity: 1;
-    }
-  }
+/* 定义 image viewer 样式。 */
 
-  @keyframes xh-fade-out {
-    from {
-      opacity: 1;
-    }
+@import '../family/action-control.css';
 
-    to {
-      opacity: 0;
-    }
-  }
-}
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
 
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
@@ -31,11 +19,22 @@
   [data-scope='image-viewer'][data-part='backdrop'] {
     position: fixed;
     inset: 0;
-    z-index: var(--xh-image-viewer-backdrop-layer, var(--xh-layer-modal));
+    z-index: var(--xh-image-viewer-backdrop-layer, var(--xh-_layer, var(--xh-layer-modal)));
     /* 看片要压住页面底色，遮罩比普通对话框更深 */
     background: var(--xh-image-viewer-backdrop-bg, color-mix(in oklab, var(--xh-color-neutral-950) 78%, transparent));
   }
 
+  /* 同一层底色之上再糊背后的页面 */
+  [data-scope='image-viewer'][data-part='backdrop'][data-variant='blur'] {
+    -webkit-backdrop-filter: blur(var(--xh-image-viewer-backdrop-blur, var(--xh-overlay-backdrop-blur)));
+    backdrop-filter: blur(var(--xh-image-viewer-backdrop-blur, var(--xh-overlay-backdrop-blur)));
+  }
+
+  /* 去掉底色，只留下这一层吃指针：交互外关闭与滚动锁定照旧 */
+  [data-scope='image-viewer'][data-part='backdrop'][data-variant='transparent'] {
+    background: transparent;
+  }
+
   [data-scope='image-viewer'][data-part='backdrop'][data-state='open'] {
     animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
   }
@@ -47,7 +46,7 @@
   [data-scope='image-viewer'][data-part='positioner'] {
     position: fixed;
     inset: 0;
-    z-index: var(--xh-image-viewer-layer, var(--xh-layer-modal));
+    z-index: var(--xh-image-viewer-layer, var(--xh-_layer, var(--xh-layer-modal)));
     display: flex;
     align-items: center;
     justify-content: center;
@@ -58,8 +57,12 @@
        既不让页面上的层号插进来，也不让它们漏出去压住别人 */
     isolation: isolate;
 
-    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
-    --xh-icon-size: var(--xh-image-viewer-icon-size, var(--xh-glyph-size-text));
+    /* 作者塞进浮层的图标：内容层给一档 md 的尺，十颗钮各自再按 Action Control 档位覆盖 */
+    --xh-icon-size: var(--xh-image-viewer-icon-size, var(--xh-glyph-size-md));
+    /* 十颗钮共用的深色 chrome：压在使用者的图片上的半透明深底，是这一层自己的面，不取页面语义面 */
+    --xh-_image-viewer-chrome-bg: var(--xh-image-viewer-chrome-bg, color-mix(in oklab, var(--xh-color-neutral-950) 55%, transparent));
+    --xh-_image-viewer-chrome-bg-hover: var(--xh-image-viewer-action-bg-hover, color-mix(in oklab, var(--xh-color-neutral-950) 70%, transparent));
+    --xh-_image-viewer-chrome-bg-active: var(--xh-image-viewer-action-bg-active, color-mix(in oklab, var(--xh-color-neutral-950) 80%, transparent));
 
     position: relative;
     inline-size: 100%;
@@ -72,7 +75,9 @@
     color: var(--xh-image-viewer-fg, var(--xh-color-neutral-0));
   }
 
+  /* 在场那一档才提前备好合成层：属性随 data-state 一起消失，收起后不长期占着 */
   [data-scope='image-viewer'][data-part='content'][data-state='open'] {
+    will-change: opacity;
     animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
   }
 
@@ -92,135 +97,181 @@
     touch-action: none;
   }
 
-  [data-scope='image-viewer'][data-part='viewport'][data-panning] {
+  [data-scope='image-viewer'][data-part='viewport'][data-dragging] {
     cursor: grabbing;
   }
 
+  /* 原图还在路上：指针先报出来，此刻拖也没有东西可拖 */
+  [data-scope='image-viewer'][data-part='viewport'][data-loading] {
+    cursor: progress;
+  }
+
+  /* 取图期间在画面正中垫一块占位面：不垫的话打开一张几 MB 的原图，
+     台前是一整块什么都没有的暗底，用户分不清是在加载还是这张图坏了 */
+  [data-scope='image-viewer'][data-part='viewport'][data-loading]::after {
+    content: '';
+    position: absolute;
+    inline-size: var(--xh-image-viewer-loading-size, calc(var(--xh-control-h-lg) * 3));
+    block-size: var(--xh-image-viewer-loading-size, calc(var(--xh-control-h-lg) * 3));
+    border-radius: var(--xh-image-viewer-loading-radius, var(--xh-shape-surface));
+    background: var(--xh-image-viewer-loading-bg, var(--xh-bg-surface-raised));
+  }
+
   [data-scope='image-viewer'][data-part='image'] {
     max-inline-size: 90%;
     max-block-size: 85%;
     user-select: none;
     /* 变换是内联 style 写的，只给缩放旋转一点缓动；拖拽平移要跟手，不缓 */
-    transition: transform var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+    transition: transform var(--xh-motion-duration-micro) var(--xh-motion-ease-continuous);
   }
 
-  [data-scope='image-viewer'][data-part='image'][data-panning] {
+  /* 拖拽期间变换每帧都在改：只在这一档备好合成层，松手后随 data-dragging 一起撤掉 */
+  [data-scope='image-viewer'][data-part='image'][data-dragging] {
     transition: none;
+    will-change: transform;
   }
 
-  /* —— 悬浮件共用：半透明深底加浅字 —— */
+  /* —— 悬浮件共用：半透明深底加浅字 ——
+     四件都钉在铺满视口的那一层的边上，贴边一律与安全区取大的一头：刘海、圆角与
+     底部横条压住的那一段由系统给出，贴边比它窄时钮会被切掉一角；桌面上 env() 恒为 0。
+     安全区只有物理方向的四个名字，行内轴上两侧同取较宽的那一段，RTL 下不会翻错边。
+     工具条是容器、计数是一行字的气泡，各按身份取圆角（surface / control，§6.3），
+     --xh-image-viewer-overlay-radius 仍是两者共用的使用者入口；翻页钮的面走下面的桥接槽 */
   [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='counter'] {
     position: absolute;
     z-index: 1;
-    background: var(--xh-image-viewer-chrome-bg, color-mix(in oklab, var(--xh-color-neutral-950) 55%, transparent));
+    background: var(--xh-_image-viewer-chrome-bg);
     color: inherit;
     border: none;
-    border-radius: var(--xh-image-viewer-overlay-radius, var(--xh-shape-pill));
   }
 
   [data-scope='image-viewer'][data-part='toolbar'] {
-    inset-block-end: var(--xh-space-6);
+    inset-block-end: max(var(--xh-space-6), env(safe-area-inset-bottom));
     inset-inline-start: 50%;
     translate: -50% 0;
     display: flex;
     align-items: center;
     gap: var(--xh-image-viewer-toolbar-gap, var(--xh-space-1));
     padding: var(--xh-image-viewer-toolbar-padding, var(--xh-space-1_5) var(--xh-space-3));
+    border-radius: var(--xh-image-viewer-toolbar-radius-outer, var(--xh-image-viewer-overlay-radius, var(--xh-shape-surface)));
   }
 
-  /* 工具条里的按钮：底色交给工具条，本体只管命中区 */
+  /* 工具条里的七颗钮：接 Action Control icon 档 xs（24px 视觉盒），底色交给工具条，本体只管命中区与按压。
+     悬停 / 按下的底从 chrome 那层深底派生，不取页面的 --xh-bg-subtle-* 阶梯。
+     position 交给配方的 relative：粗指针下 44px 命中区 ::after 以钮自身为包含块；
+     这里若写 static，七块命中区会一起以工具条为包含块、彼此盖住，触屏上只剩最后一颗可点 */
   [data-scope='image-viewer'][data-part='toolbar'] > [data-part] {
-    position: static;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    inline-size: var(--xh-control-action-size);
-    block-size: var(--xh-control-action-size);
-    background: none;
-    border: none;
-    border-radius: var(--xh-image-viewer-toolbar-radius, var(--xh-shape-control));
-    color: inherit;
-    font-size: var(--xh-glyph-size-sm);
-    cursor: pointer;
+    --xh-action-bg-rest: transparent;
+    --xh-action-bg-hover: var(--xh-_image-viewer-chrome-bg-hover);
+    --xh-action-bg-pressed: var(--xh-_image-viewer-chrome-bg-active);
+    --xh-action-bg-focus-visible: transparent;
+    --xh-action-bg-disabled: transparent;
+    --xh-action-fg-rest: currentColor;
+    --xh-action-fg-hover: currentColor;
+    --xh-action-fg-pressed: currentColor;
+    --xh-action-fg-focus-visible: currentColor;
+    --xh-action-fg-disabled: currentColor;
+    --xh-action-border-rest: transparent;
+    --xh-action-border-hover: transparent;
+    --xh-action-border-pressed: transparent;
+    --xh-action-border-focus-visible: transparent;
+    --xh-action-border-disabled: transparent;
+    --xh-action-radius: var(--xh-image-viewer-toolbar-radius, var(--xh-_action-profile-radius));
+    --xh-icon-size: var(--xh-image-viewer-icon-size, var(--xh-_action-profile-glyph-size));
   }
 
   [data-scope='image-viewer'][data-part='counter'] {
-    inset-block-start: var(--xh-space-6);
+    inset-block-start: max(var(--xh-space-6), env(safe-area-inset-top));
     inset-inline-start: 50%;
     translate: -50% 0;
     padding: var(--xh-image-viewer-counter-padding, var(--xh-space-1) var(--xh-space-3));
+    border-radius: var(--xh-image-viewer-counter-radius, var(--xh-image-viewer-overlay-radius, var(--xh-shape-control)));
     font-size: var(--xh-text-secondary-size);
   }
 
+  /* 两颗翻页钮：浮在图上的单图标圆钮，接 Action Control floating 档 md（48px，正方盒取 circle，§6.3）。
+     面桥接到自家深色 chrome：跟的是图上那层半透明深底不是页面底色，所以不取 frosted 缺省面，
+     也不取语义档的 --xh-bg-subtle-*；到头时是原生 disabled，压不动的东西不给回应 */
   [data-scope='image-viewer'][data-part='prev-trigger'],
   [data-scope='image-viewer'][data-part='next-trigger'] {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    inline-size: var(--xh-control-h-lg);
-    block-size: var(--xh-control-h-lg);
-    font-size: var(--xh-glyph-size-md);
-    cursor: pointer;
+    --xh-action-bg-rest: var(--xh-_image-viewer-chrome-bg);
+    --xh-action-bg-hover: var(--xh-_image-viewer-chrome-bg-hover);
+    --xh-action-bg-pressed: var(--xh-_image-viewer-chrome-bg-active);
+    --xh-action-bg-focus-visible: var(--xh-_image-viewer-chrome-bg);
+    --xh-action-bg-disabled: var(--xh-_image-viewer-chrome-bg);
+    --xh-action-fg-rest: currentColor;
+    --xh-action-fg-hover: currentColor;
+    --xh-action-fg-pressed: currentColor;
+    --xh-action-fg-focus-visible: currentColor;
+    --xh-action-fg-disabled: currentColor;
+    --xh-action-border-rest: transparent;
+    --xh-action-border-hover: transparent;
+    --xh-action-border-pressed: transparent;
+    --xh-action-border-focus-visible: transparent;
+    --xh-action-border-disabled: transparent;
+    --xh-action-radius: var(--xh-image-viewer-overlay-radius, var(--xh-_action-profile-radius));
+    --xh-icon-size: var(--xh-image-viewer-icon-size, var(--xh-_action-profile-glyph-size));
+
+    position: absolute;
+    z-index: 1;
   }
 
   [data-scope='image-viewer'][data-part='prev-trigger'] {
-    inset-inline-start: var(--xh-space-6);
+    inset-inline-start: max(var(--xh-space-6), env(safe-area-inset-left), env(safe-area-inset-right));
     inset-block-start: 50%;
     translate: 0 -50%;
   }
 
   [data-scope='image-viewer'][data-part='next-trigger'] {
-    inset-inline-end: var(--xh-space-6);
+    inset-inline-end: max(var(--xh-space-6), env(safe-area-inset-left), env(safe-area-inset-right));
     inset-block-start: 50%;
     translate: 0 -50%;
   }
 
-  /* 右上角的关闭钮：与翻页钮同底同高，但圆角走控件档，按下有缩放 */
+  /* 右上角的关闭钮：接 Action Control icon 档 lg（40px，触控靶走 lg），圆角走控件档；面与翻页钮同一层深色 chrome */
   [data-scope='image-viewer'][data-part='close-trigger'] {
+    --xh-action-bg-rest: var(--xh-_image-viewer-chrome-bg);
+    --xh-action-bg-hover: var(--xh-image-viewer-close-bg-hover, var(--xh-_image-viewer-chrome-bg-hover));
+    --xh-action-bg-pressed: var(--xh-image-viewer-close-bg-active, var(--xh-_image-viewer-chrome-bg-active));
+    --xh-action-bg-focus-visible: var(--xh-_image-viewer-chrome-bg);
+    --xh-action-bg-disabled: var(--xh-_image-viewer-chrome-bg);
+    /* 看图时整块 chrome 盖住页面，叉的颜色随那层继承；使用者要单独换叉的颜色走这支槽 */
+    --xh-action-fg-rest: var(--xh-image-viewer-close-fg, currentColor);
+    --xh-action-fg-hover: var(--xh-image-viewer-close-fg, currentColor);
+    --xh-action-fg-pressed: var(--xh-image-viewer-close-fg, currentColor);
+    --xh-action-fg-focus-visible: var(--xh-image-viewer-close-fg, currentColor);
+    --xh-action-fg-disabled: var(--xh-image-viewer-close-fg, currentColor);
+    --xh-action-border-rest: transparent;
+    --xh-action-border-hover: transparent;
+    --xh-action-border-pressed: transparent;
+    --xh-action-border-focus-visible: transparent;
+    --xh-action-border-disabled: transparent;
+    --xh-action-radius: var(--xh-image-viewer-close-radius, var(--xh-shape-control));
+    --xh-action-visual-size: var(--xh-image-viewer-close-size, var(--xh-_action-profile-visual-size));
+    --xh-icon-size: var(--xh-image-viewer-icon-size, var(--xh-_action-profile-glyph-size));
+
     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);
+    inset-block-start: max(var(--xh-space-6), env(safe-area-inset-top));
+    inset-inline-end: max(var(--xh-space-6), env(safe-area-inset-left), env(safe-area-inset-right));
   }
 
-  [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);
+  /* 三颗钮的面是一层深色纱，纱底下是使用者的图片，环色算不出稳定的取值。
+     content 把前景钉死在浅字上、三颗钮的前景随它继承，环取 currentColor 即是那支浅字，
+     不随图片内容也不随主题翻 */
+  [data-scope='image-viewer'][data-part='close-trigger']:focus-visible,
+  [data-scope='image-viewer'][data-part='prev-trigger']:focus-visible,
+  [data-scope='image-viewer'][data-part='next-trigger']:focus-visible {
+    --xh-action-ring-color-focus-visible: currentColor;
   }
 
-  [data-scope='image-viewer'] button[data-part]:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
+  [data-scope='image-viewer'][data-part='close-trigger'][hidden] {
+    display: none;
   }
 
   [data-scope='image-viewer'] button[data-part]:disabled {
     opacity: var(--xh-state-disabled-opacity);
-    cursor: not-allowed;
   }
 
   /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
@@ -328,7 +379,17 @@
   [data-scope='image-viewer'][data-part='positioner'][hidden],
   [data-scope='image-viewer'][data-part='viewport'][hidden],
   [data-scope='image-viewer'][data-part='toolbar'][hidden],
+  [data-scope='image-viewer'][data-part='prev-trigger'][hidden],
   [data-scope='image-viewer'][data-part='next-trigger'][hidden] {
     display: none;
   }
+
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    [data-scope='image-viewer'][data-part='backdrop'],
+    [data-scope='image-viewer'][data-part='positioner'] {
+      display: none;
+    }
+  }
 }

package/css/image.css

@@ -1,3 +1,13 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 image 样式。 */
+
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='image'] {
@@ -22,11 +32,30 @@
     display: none;
   }
 
-  /* 不声明 display：加载完成前的 hidden 直接交给浏览器的 [hidden] 规则收起 */
+  /* 不声明 display：加载完成前的 hidden 直接交给浏览器的 [hidden] 规则收起。
+     载完那一刻 hidden 撤掉、这个节点从不显示变为显示，淡入在那一刻起跑，
+     图片不是硬切上来盖掉占位层 */
   [data-scope='image'][data-part='image'] {
     inline-size: 100%;
     block-size: 100%;
     object-fit: var(--xh-image-fit, cover);
+    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 铺满图位的占位层：加载期间占住画面，作者往里放骨架屏或模糊小图 */
+  [data-scope='image'][data-part='placeholder'] {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--xh-image-placeholder-bg, var(--xh-bg-subtle-hover));
+    color: var(--xh-image-placeholder-fg, var(--xh-fg-subtle));
+  }
+
+  /* display 会盖掉 hidden 属性的 UA 规则：图片落位与失败后都靠这条收起 */
+  [data-scope='image'][data-part='placeholder'][hidden] {
+    display: none;
   }
 
   [data-scope='image'][data-part='fallback'] {