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

package/css/menubar.css

@@ -1,18 +1,23 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='menubar'] {
+    --xh-menubar-skin: 1;
+  }
+
   /* 一排 trigger。主轴跟着 data-orientation 走：菜单栏本身可以横排也可以竖排 */
   [data-scope='menubar'][data-part='root'] {
     /* 尺寸档只换这五个私有槽，trigger 与菜单里的条目都从 root 继承它们，
        换档不必给每个部件各写一条选择器。菜单浮层在 positioner 里、也是 root 的后代，一并继承 */
     --xh-_menubar-trigger-py: var(--xh-space-1);
     --xh-_menubar-trigger-px: var(--xh-control-px-sm);
-    --xh-_menubar-item-py: var(--xh-space-2);
-    --xh-_menubar-item-px: var(--xh-control-px-sm);
+    --xh-_menubar-item-py: var(--xh-space-1_5);
+    --xh-_menubar-item-px: var(--xh-control-px-md);
     --xh-_menubar-font-size: var(--xh-text-body-size);
 
-    /* 高亮底随语气走：展开着的那张菜单的 trigger 与菜单里的高亮条目共用这一档。
-       没写 data-tone 时 --xh-_tone-subtle-hover 没被声明，退回原来的中性底。
+    /* 展开着的那张菜单的 trigger 走品牌淡底强档，随语气换色相；没写 data-tone 时退回品牌淡底。
+       悬停与键盘焦点恒中性灰轻档、不接语气槽——两档同色相的话哪张开着就认不出来了。
        聚焦环不在其列，它恒是 --xh-ring-focus */
-    --xh-_menubar-highlight-bg: var(--xh-_tone-subtle-hover, var(--xh-bg-subtle-hover));
+    --xh-_menubar-active-bg: var(--xh-_tone-subtle, var(--xh-bg-brand-subtle));
 
     display: flex;
     align-items: center;
@@ -34,21 +39,21 @@
   }
 
   /* —— 尺寸 —— */
-  /* 缺省档写在上面的基础规则里。内边距的缺省档已经落在控件内边距尺的 sm 那一格，
-     往下没有更小的一格，sm 档改取空间尺；lg 档回到控件尺的下一格 */
+  /* 缺省档写在上面的基础规则里。trigger 的行内内缩缺省落在控件尺 sm 档、再往下取空间尺；
+     条目纵向走 space 档、行内内缩走 control-px 档（随密度轴），换档各挪一级 */
   [data-scope='menubar'][data-part='root'][data-size='sm'] {
     --xh-_menubar-trigger-py: var(--xh-space-0_5);
     --xh-_menubar-trigger-px: var(--xh-space-1_5);
-    --xh-_menubar-item-py: var(--xh-space-1_5);
-    --xh-_menubar-item-px: var(--xh-space-1_5);
+    --xh-_menubar-item-py: var(--xh-space-1);
+    --xh-_menubar-item-px: var(--xh-control-px-sm);
     --xh-_menubar-font-size: var(--xh-font-size-sm);
   }
 
   [data-scope='menubar'][data-part='root'][data-size='lg'] {
     --xh-_menubar-trigger-py: var(--xh-space-2);
     --xh-_menubar-trigger-px: var(--xh-control-px-md);
-    --xh-_menubar-item-py: var(--xh-space-3);
-    --xh-_menubar-item-px: var(--xh-control-px-md);
+    --xh-_menubar-item-py: var(--xh-space-2);
+    --xh-_menubar-item-px: var(--xh-control-px-lg);
     --xh-_menubar-font-size: var(--xh-font-size-lg);
   }
 
@@ -78,15 +83,23 @@
     white-space: nowrap;
     cursor: pointer;
     user-select: none;
+    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   [data-scope='menubar'][data-part='trigger'][hidden] {
     display: none;
   }
 
-  /* 展开着的那一项与指针悬停共用一套底色：菜单栏里"哪一张开着"必须一眼看得出来 */
-  [data-scope='menubar'][data-part='trigger']:not([data-disabled]):is(:hover, [data-state='open']) {
-    background: var(--xh-menubar-trigger-bg-active, var(--xh-_menubar-highlight-bg));
+  /* 指针悬停走中性灰轻档 */
+  [data-scope='menubar'][data-part='trigger']:not([data-disabled]):hover {
+    background: var(--xh-menubar-trigger-bg-hover, var(--xh-bg-subtle));
+  }
+
+  /* 展开着的那一张是打开路径，走品牌淡底强档：菜单栏里"哪一张开着"必须一眼看得出来。
+     不加粗：横排的栏加粗会推挤相邻触发器。
+     必须排在轻档之后：指针回到它身上时同特指度靠书写顺序压过轻档 */
+  [data-scope='menubar'][data-part='trigger']:not([data-disabled])[data-state='open'] {
+    background: var(--xh-menubar-trigger-bg-active, var(--xh-_menubar-active-bg));
   }
 
   /* trigger 自带 Tab 位（整条菜单栏唯一的那个），必须画得出焦点 */
@@ -147,13 +160,6 @@
     animation: xh-menubar-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
   }
 
-  /* 关掉动效的用户不该被涨开动画晃一下；这里只管本组件，公共那份不动 */
-  @media (prefers-reduced-motion: reduce) {
-    [data-scope='menubar'][data-part='content'][data-state='open'] {
-      animation-duration: 0.01ms;
-    }
-  }
-
   [data-scope='menubar'][data-part='group'] {
     display: flex;
     flex-direction: column;
@@ -189,10 +195,13 @@
     border-radius: var(--xh-menubar-item-radius, var(--xh-shape-control));
     color: var(--xh-menubar-item-fg, var(--xh-fg-default));
     font-size: var(--xh-menubar-item-font-size, var(--xh-_menubar-font-size));
-    line-height: var(--xh-leading-none);
+    line-height: var(--xh-menubar-item-leading, var(--xh-leading-normal));
     white-space: nowrap;
     cursor: pointer;
     user-select: none;
+    transition:
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   /* 条目可以按需收起（按上下文过滤掉的命令），有 display 就得补这条 */
@@ -200,11 +209,11 @@
     display: none;
   }
 
-  /* 键盘高亮与指针高亮共用一套底色：条目本身承载焦点，不另画描边。
+  /* 悬停与键盘焦点共用中性灰轻档：条目本身承载焦点，不另画描边。
      data-highlighted 跟的是连接层记的焦点条目，与 :focus 说的是同一件事，
      子部件够不着那个伪类，只能读这个标记 */
   [data-scope='menubar'][data-part='item']:not([data-disabled]):is(:hover, :focus, [data-highlighted]) {
-    background: var(--xh-menubar-item-bg-highlight, var(--xh-_menubar-highlight-bg));
+    background: var(--xh-menubar-item-bg-hover, var(--xh-bg-subtle));
   }
 
   [data-scope='menubar'][data-part='item']:focus {
@@ -260,7 +269,7 @@
   @keyframes xh-menubar-in {
     from {
       opacity: 0;
-      scale: 0.96;
+      scale: var(--xh-motion-scale-enter);
     }
 
     to {

package/css/navigation-menu.css

@@ -3,7 +3,7 @@
   @keyframes xh-navigation-menu-in {
     from {
       opacity: 0;
-      translate: 0 -4px;
+      translate: 0 calc(-1 * var(--xh-motion-distance-sm));
     }
 
     to {
@@ -14,6 +14,11 @@
 }
 
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='navigation-menu'] {
+    --xh-navigation-menu-skin: 1;
+  }
+
   /* 根节点是 nav 地标，不参与排版；给 relative 是为了让共享外壳（viewport）有个定位参照系。
      这里不给 display，UA 的 [hidden]{display:none} 就仍然压得住 */
   [data-scope='navigation-menu'][data-part='root'] {

package/css/number-animation.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='number-animation'] {
+    --xh-number-animation-skin: 1;
+  }
+
   [data-scope='number-animation'][data-part='root'] {
     /* 不写尺寸就跟着上下文的字号走：这个数常常摆在别人的标题、卡片标题或统计数值槽里，
        自带一个字号只会跟摆放它的地方打架。三个档位各自换掉这个私有槽 */

package/css/number-field.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='number-field'] {
+    --xh-number-field-skin: 1;
+  }
+
   /* 与文本框同一套堆叠：标签一行、输入行一行。
      加减钮与输入框中间那层包裹归作者，这里不碰，三者各自把高度对齐即可成一体 */
   [data-scope='number-field'][data-part='root'] {
@@ -12,18 +17,18 @@
 
     /* 形态档只换这几个私有槽：输入框的底与描边，加减钮的底与描边 */
     --xh-_number-field-bg: var(--xh-bg-canvas);
-    --xh-_number-field-border: var(--xh-border-default);
-    --xh-_number-field-border-hover: var(--xh-border-strong);
+    --xh-_number-field-border: var(--xh-border-control);
+    --xh-_number-field-border-hover: var(--xh-border-control-hover);
     --xh-_number-field-trigger-bg: var(--xh-bg-subtle);
     --xh-_number-field-trigger-bg-hover: var(--xh-bg-subtle-hover);
     --xh-_number-field-trigger-bg-active: var(--xh-bg-subtle-active);
-    --xh-_number-field-trigger-border: var(--xh-border-default);
-    --xh-_number-field-trigger-border-hover: var(--xh-border-strong);
+    --xh-_number-field-trigger-border: var(--xh-border-control);
+    --xh-_number-field-trigger-border-hover: var(--xh-border-control-hover);
 
     /* 语气只落在聚焦这一处：环与聚焦态描边。框里的数字不归它管。
        没写 data-tone 时 --xh-_tone 没被声明，退回原来的聚焦环色与常态描边 */
     --xh-_number-field-ring: var(--xh-ring-focus);
-    --xh-_number-field-border-focus: var(--xh-number-field-input-border, var(--xh-_tone, var(--xh-border-default)));
+    --xh-_number-field-border-focus: var(--xh-number-field-input-border, var(--xh-_tone, var(--xh-border-control)));
 
     display: inline-flex;
     flex-direction: column;
@@ -58,14 +63,14 @@
      输入框没有实心档：填满一个要往里打字的框，字与底就没法同时读 */
   [data-scope='number-field'][data-part='root'][data-variant='outline'] {
     --xh-_number-field-bg: var(--xh-bg-canvas);
-    --xh-_number-field-border: var(--xh-border-default);
-    --xh-_number-field-border-hover: var(--xh-border-strong);
+    --xh-_number-field-border: var(--xh-border-control);
+    --xh-_number-field-border-hover: var(--xh-border-control-hover);
     --xh-_number-field-trigger-bg: var(--xh-bg-subtle);
     --xh-_number-field-trigger-bg-hover: var(--xh-bg-subtle-hover);
     --xh-_number-field-trigger-bg-active: var(--xh-bg-subtle-active);
-    --xh-_number-field-trigger-border: var(--xh-border-default);
-    --xh-_number-field-trigger-border-hover: var(--xh-border-strong);
-    --xh-_number-field-border-focus: var(--xh-number-field-input-border, var(--xh-_tone, var(--xh-border-default)));
+    --xh-_number-field-trigger-border: var(--xh-border-control);
+    --xh-_number-field-trigger-border-hover: var(--xh-border-control-hover);
+    --xh-_number-field-border-focus: var(--xh-number-field-input-border, var(--xh-_tone, var(--xh-border-control)));
   }
 
   /* 填充式：底色顶替描边表达边界。描边只退成透明而不去掉，1px 的位置留着，
@@ -73,26 +78,26 @@
   [data-scope='number-field'][data-part='root'][data-variant='subtle'] {
     --xh-_number-field-bg: var(--xh-_tone-subtle, var(--xh-bg-subtle));
     --xh-_number-field-border: transparent;
-    --xh-_number-field-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+    --xh-_number-field-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
     --xh-_number-field-trigger-bg: var(--xh-_tone-subtle, var(--xh-bg-subtle));
     --xh-_number-field-trigger-bg-hover: var(--xh-_tone-subtle-hover, var(--xh-bg-subtle-hover));
     --xh-_number-field-trigger-bg-active: var(--xh-_tone-subtle-active, var(--xh-bg-subtle-active));
     --xh-_number-field-trigger-border: transparent;
-    --xh-_number-field-trigger-border-hover: var(--xh-_tone-border, var(--xh-border-default));
-    --xh-_number-field-border-focus: var(--xh-_tone, var(--xh-border-default));
+    --xh-_number-field-trigger-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
+    --xh-_number-field-border-focus: var(--xh-_tone, var(--xh-border-control));
   }
 
   /* 无框：底与描边都透明，平时只看得见数字，悬停与聚焦才浮出边界 */
   [data-scope='number-field'][data-part='root'][data-variant='ghost'] {
     --xh-_number-field-bg: transparent;
     --xh-_number-field-border: transparent;
-    --xh-_number-field-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+    --xh-_number-field-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
     --xh-_number-field-trigger-bg: transparent;
     --xh-_number-field-trigger-bg-hover: var(--xh-_tone-subtle, var(--xh-bg-subtle-hover));
     --xh-_number-field-trigger-bg-active: var(--xh-_tone-subtle-active, var(--xh-bg-subtle-active));
     --xh-_number-field-trigger-border: transparent;
-    --xh-_number-field-trigger-border-hover: var(--xh-_tone-border, var(--xh-border-default));
-    --xh-_number-field-border-focus: var(--xh-_tone, var(--xh-border-default));
+    --xh-_number-field-trigger-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
+    --xh-_number-field-border-focus: var(--xh-_tone, var(--xh-border-control));
   }
 
   [data-scope='number-field'][data-part='label'] {

package/css/page-header.css

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

package/css/pagination.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='pagination'] {
+    --xh-pagination-skin: 1;
+  }
+
   /* 根节点是 nav 地标，只负责把上一页 / 页码 / 下一页排成一行。
      页数为 0 时连接层会打 data-empty，这里不拿它做隐藏：作者常把「第 x-y 条」这类
      区间回显也写在 nav 里，整块藏掉会连那行字一起吞了，是否隐藏交给作者决定 */

package/css/pin-input.css

@@ -1,4 +1,9 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='pin-input'] {
+    --xh-pin-input-skin: 1;
+  }
+
   /* 与文本框、数字框同一套堆叠：标签一行、格子一行 */
   [data-scope='pin-input'][data-part='root'] {
     /* 尺寸档只换这四个私有槽，标题与格子都从 root 继承它们，换档不必给每个部件各写一条选择器 */
@@ -8,8 +13,8 @@
     --xh-_pin-input-label-font-size: var(--xh-text-label-size);
     /* 形态档只换这三个私有槽，缺省这一份就是描边式（描边 + 画布底） */
     --xh-_pin-input-box-bg: var(--xh-bg-canvas);
-    --xh-_pin-input-box-border: var(--xh-border-default);
-    --xh-_pin-input-box-border-hover: var(--xh-border-strong);
+    --xh-_pin-input-box-border: var(--xh-border-control);
+    --xh-_pin-input-box-border-hover: var(--xh-border-control-hover);
     /* 聚焦环与填满态的强调色随语气走。没写 data-tone 时 --xh-_tone 没被声明，退回原来的取值 */
     --xh-_pin-input-ring: var(--xh-ring-focus);
     --xh-_pin-input-accent: var(--xh-_tone, var(--xh-bg-brand));
@@ -29,22 +34,22 @@
      不做 solid：实心填充盖住了"这里能打字"这件事，输入框用不上它 */
   [data-scope='pin-input'][data-part='root'][data-variant='outline'] {
     --xh-_pin-input-box-bg: var(--xh-bg-canvas);
-    --xh-_pin-input-box-border: var(--xh-border-default);
-    --xh-_pin-input-box-border-hover: var(--xh-border-strong);
+    --xh-_pin-input-box-border: var(--xh-border-control);
+    --xh-_pin-input-box-border-hover: var(--xh-border-control-hover);
   }
 
   /* 填充式：底色说明这里是一格输入位，描边让位给底色 */
   [data-scope='pin-input'][data-part='root'][data-variant='subtle'] {
     --xh-_pin-input-box-bg: var(--xh-_tone-subtle, var(--xh-bg-subtle));
     --xh-_pin-input-box-border: transparent;
-    --xh-_pin-input-box-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+    --xh-_pin-input-box-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
   }
 
   /* 无边框、透明底：静息时格子完全隐入背景，可见反馈全靠悬停描边与聚焦环 */
   [data-scope='pin-input'][data-part='root'][data-variant='ghost'] {
     --xh-_pin-input-box-bg: transparent;
     --xh-_pin-input-box-border: transparent;
-    --xh-_pin-input-box-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+    --xh-_pin-input-box-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
   }
 
   /* —— 尺寸 —— */

package/css/popconfirm.css

@@ -1,4 +1,32 @@
+@layer xihan.motion {
+  /* 转圈的关键帧定义在本文件里：引用别处文件的动画名时那份文件不一定在场，动画会静默不跑 */
+  @keyframes xh-popconfirm-rotate {
+    to {
+      transform: rotate(1turn);
+    }
+  }
+}
+
+@layer xihan.motion {
+  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
+     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
+  @keyframes xh-fade-in {
+    from {
+      opacity: 0;
+    }
+
+    to {
+      opacity: 1;
+    }
+  }
+}
+
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='popconfirm'] {
+    --xh-popconfirm-skin: 1;
+  }
+
   /* 根只框住触发器：浮层树靠 positioner 的固定定位飞出去，不占根的盒子 */
   [data-scope='popconfirm'][data-part='root'] {
     display: inline-block;
@@ -120,6 +148,22 @@
     color: var(--xh-popconfirm-confirm-fg, var(--xh-_tone-on, var(--xh-fg-on-brand)));
   }
 
+  /* 异步确认挂起：按钮转圈、指针挂起；不是禁用，焦点与对比度都保持 */
+  [data-scope='popconfirm'][data-part='confirm-trigger'][data-loading] {
+    cursor: wait;
+  }
+
+  [data-scope='popconfirm'][data-part='confirm-trigger'][data-loading]::before {
+    content: '';
+    inline-size: 1em;
+    block-size: 1em;
+    margin-inline-end: var(--xh-space-1);
+    border: var(--xh-stroke-thin) solid transparent;
+    border-block-start-color: currentcolor;
+    border-radius: var(--xh-shape-pill);
+    animation: xh-popconfirm-rotate var(--xh-popconfirm-loading-duration, calc(var(--xh-duration-slow) * 2)) linear infinite;
+  }
+
   [data-scope='popconfirm'][data-part='confirm-trigger']:hover {
     background: var(--xh-_tone-hover, var(--xh-bg-brand-hover));
   }

package/css/popover.css

@@ -1,4 +1,23 @@
+@layer xihan.motion {
+  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
+     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
+  @keyframes xh-fade-in {
+    from {
+      opacity: 0;
+    }
+
+    to {
+      opacity: 1;
+    }
+  }
+}
+
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='popover'] {
+    --xh-popover-skin: 1;
+  }
+
   /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
   [data-scope='popover'][data-part='positioner'] {
     position: fixed;
@@ -110,40 +129,44 @@
   }
 
   /* 箭头是旋转 45° 的方块，只保留朝向锚点那两条边的描边；
-     引擎不产出箭头偏移，因此沿交叉轴固定居中 */
+     交叉轴落点由定位引擎经内联自定义属性写进来，没给时退回居中 */
   [data-scope='popover'][data-part='arrow'] {
+    --xh-_popover-arrow-size: var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size));
+    --xh-_popover-arrow-x: 50%;
+    --xh-_popover-arrow-y: 50%;
+
     position: absolute;
-    inline-size: var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size));
-    block-size: var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size));
+    inline-size: var(--xh-_popover-arrow-size);
+    block-size: var(--xh-_popover-arrow-size);
     background: var(--xh-popover-bg, var(--xh-bg-surface));
     border: var(--xh-stroke-thin) solid var(--xh-popover-border, var(--xh-border-default));
     rotate: 45deg;
   }
 
   [data-scope='popover'][data-part='arrow'][data-placement^='bottom'] {
-    inset-block-start: calc(var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size)) / -2);
-    inset-inline-start: calc(50% - var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size)) / 2);
+    inset-block-start: calc(var(--xh-_popover-arrow-size) / -2);
+    inset-inline-start: calc(var(--xh-_popover-arrow-x) - var(--xh-_popover-arrow-size) / 2);
     border-block-end: 0;
     border-inline-end: 0;
   }
 
   [data-scope='popover'][data-part='arrow'][data-placement^='top'] {
-    inset-block-end: calc(var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size)) / -2);
-    inset-inline-start: calc(50% - var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size)) / 2);
+    inset-block-end: calc(var(--xh-_popover-arrow-size) / -2);
+    inset-inline-start: calc(var(--xh-_popover-arrow-x) - var(--xh-_popover-arrow-size) / 2);
     border-block-start: 0;
     border-inline-start: 0;
   }
 
   [data-scope='popover'][data-part='arrow'][data-placement^='right'] {
-    inset-inline-start: calc(var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size)) / -2);
-    inset-block-start: calc(50% - var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size)) / 2);
+    inset-inline-start: calc(var(--xh-_popover-arrow-size) / -2);
+    inset-block-start: calc(var(--xh-_popover-arrow-y) - var(--xh-_popover-arrow-size) / 2);
     border-block-start: 0;
     border-inline-end: 0;
   }
 
   [data-scope='popover'][data-part='arrow'][data-placement^='left'] {
-    inset-inline-end: calc(var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size)) / -2);
-    inset-block-start: calc(50% - var(--xh-popover-arrow-size, var(--xh-overlay-arrow-size)) / 2);
+    inset-inline-end: calc(var(--xh-_popover-arrow-size) / -2);
+    inset-block-start: calc(var(--xh-_popover-arrow-y) - var(--xh-_popover-arrow-size) / 2);
     border-block-end: 0;
     border-inline-start: 0;
   }

package/css/popselect.css

@@ -1,4 +1,23 @@
+@layer xihan.motion {
+  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
+     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
+  @keyframes xh-fade-in {
+    from {
+      opacity: 0;
+    }
+
+    to {
+      opacity: 1;
+    }
+  }
+}
+
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='popselect'] {
+    --xh-popselect-skin: 1;
+  }
+
   [data-scope='popselect'][data-part='root'] {
     /* 尺寸档只换这四个私有槽，触发器与条目都从 root 继承它们，换档不必给每个部件各写一条选择器。
        浮层在 positioner 里、也是 root 的后代，一并继承 */
@@ -9,14 +28,13 @@
 
     /* 形态档只换这三个槽：缺省即 outline（描边 + 画布底） */
     --xh-_popselect-trigger-bg: var(--xh-bg-canvas);
-    --xh-_popselect-trigger-border: var(--xh-border-default);
-    --xh-_popselect-trigger-border-hover: var(--xh-border-strong);
+    --xh-_popselect-trigger-border: var(--xh-border-control);
+    --xh-_popselect-trigger-border-hover: var(--xh-border-control-hover);
 
-    /* 强调色随语气走，只落在聚焦与选中上，正文文字色不动。
-       没写 data-tone 时 --xh-_tone 没被声明，三处都退回原来的取值 */
+    /* 聚焦环恒用固定环色；强调色随语气走，只落在勾选标记与选中文字上，正文文字色不动。
+       没写 data-tone 时 --xh-_tone 没被声明，两处都退回原来的取值 */
     --xh-_popselect-ring: var(--xh-ring-focus);
     --xh-_popselect-accent: var(--xh-_tone, var(--xh-bg-brand));
-    --xh-_popselect-item-highlight-bg: var(--xh-_tone-subtle-hover, var(--xh-bg-subtle-hover));
     --xh-_popselect-item-selected-fg: var(--xh-_tone-fg, var(--xh-fg-brand-strong));
 
     display: inline-flex;
@@ -42,21 +60,21 @@
   /* 形态只决定描边与底色怎么用，用哪族颜色由 data-tone 决定 */
   [data-scope='popselect'][data-part='root'][data-variant='outline'] {
     --xh-_popselect-trigger-bg: var(--xh-bg-canvas);
-    --xh-_popselect-trigger-border: var(--xh-border-default);
-    --xh-_popselect-trigger-border-hover: var(--xh-border-strong);
+    --xh-_popselect-trigger-border: var(--xh-border-control);
+    --xh-_popselect-trigger-border-hover: var(--xh-border-control-hover);
   }
 
   /* 填充式：底色顶替描边，悬停时才浮出一道淡边 */
   [data-scope='popselect'][data-part='root'][data-variant='subtle'] {
     --xh-_popselect-trigger-bg: var(--xh-_tone-subtle, var(--xh-bg-subtle));
     --xh-_popselect-trigger-border: transparent;
-    --xh-_popselect-trigger-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+    --xh-_popselect-trigger-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
   }
 
   [data-scope='popselect'][data-part='root'][data-variant='ghost'] {
     --xh-_popselect-trigger-bg: transparent;
     --xh-_popselect-trigger-border: transparent;
-    --xh-_popselect-trigger-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+    --xh-_popselect-trigger-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
   }
 
   [data-scope='popselect'][data-part='trigger'] {
@@ -130,8 +148,14 @@
     display: none;
   }
 
-  /* 容器只是焦点域兜底落点，落焦不画环：高亮永远长在条目上 */
-  [data-scope='popselect'][data-part='content']:focus-visible {
+  /* 焦点落在容器上只有一种情形：指针打开、无选中值、还没有任何条目当锚点。
+     那一刻它认领着 Tab 位，环画在浮层内沿；有锚点时环长在条目上，容器不再画 */
+  [data-scope='popselect'][data-part='content'][tabindex='0']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: calc(-1 * var(--xh-ring-width));
+  }
+
+  [data-scope='popselect'][data-part='content']:not([tabindex='0']):focus-visible {
     outline: none;
   }
 
@@ -143,8 +167,8 @@
     display: flex;
     align-items: center;
     gap: var(--xh-popselect-item-gap, var(--xh-_popselect-gap));
-    padding-block: var(--xh-popselect-item-py, var(--xh-space-1));
-    padding-inline: var(--xh-popselect-item-px, var(--xh-control-px-sm));
+    padding-block: var(--xh-popselect-item-py, var(--xh-space-1_5));
+    padding-inline: var(--xh-popselect-item-px, var(--xh-control-px-md));
     border-radius: var(--xh-popselect-item-radius, var(--xh-shape-control));
     color: var(--xh-popselect-item-fg, var(--xh-fg-default));
     font-size: var(--xh-popselect-item-font-size, var(--xh-_popselect-font-size));
@@ -153,11 +177,14 @@
     white-space: nowrap;
     cursor: pointer;
     user-select: none;
+    transition:
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
-  /* 键盘高亮与指针高亮共用一套底色：条目本身承载焦点，不另画描边 */
+  /* 悬停与键盘锚点共用中性灰轻档：条目本身承载焦点，不另画描边 */
   [data-scope='popselect'][data-part='item']:not([data-disabled]):is(:hover, [data-highlighted]) {
-    background: var(--xh-popselect-item-bg-highlight, var(--xh-_popselect-item-highlight-bg));
+    background: var(--xh-popselect-item-bg-hover, var(--xh-bg-subtle));
   }
 
   /* 选中只换文字色与字重，配合行尾的 ✓ 标记；底色整条通道留给高亮，两者因此能同时看见 */
@@ -166,7 +193,14 @@
     font-weight: var(--xh-popselect-item-font-weight-selected, var(--xh-font-weight-medium));
   }
 
-  [data-scope='popselect'][data-part='item']:focus {
+  /* 键盘走到条目上要画环：轻档底色对白底只有 1.1:1，够不上焦点指示器的对比度要求。
+     指针悬停走的是程序化聚焦，鼠标模态下 :focus-visible 不匹配，不会误画 */
+  [data-scope='popselect'][data-part='item']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: calc(-1 * var(--xh-ring-width));
+  }
+
+  [data-scope='popselect'][data-part='item']:focus:not(:focus-visible) {
     outline: none;
   }