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

package/css/accordion.css

@@ -1,5 +1,13 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='accordion'] {
+    --xh-accordion-skin: 1;
+  }
+
   [data-scope='accordion'][data-part='root'] {
+    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-accordion-icon-size, var(--xh-glyph-size-text));
+
     /* 尺寸档只换这四个私有槽，标题栏从 root 继承它们，换档不必给每个部件各写一条选择器 */
     --xh-_accordion-trigger-h: var(--xh-control-h-md);
     --xh-_accordion-trigger-px: var(--xh-control-px-md);
@@ -26,18 +34,18 @@
     --xh-_accordion-trigger-h: var(--xh-control-h-sm);
     --xh-_accordion-trigger-px: var(--xh-control-px-sm);
     --xh-_accordion-trigger-gap: var(--xh-control-gap-sm);
-    --xh-_accordion-trigger-font-size: var(--xh-font-size-sm);
+    --xh-_accordion-trigger-font-size: var(--xh-control-font-sm);
   }
 
   [data-scope='accordion'][data-part='root'][data-size='lg'] {
     --xh-_accordion-trigger-h: var(--xh-control-h-lg);
     --xh-_accordion-trigger-px: var(--xh-control-px-lg);
     --xh-_accordion-trigger-gap: var(--xh-control-gap-lg);
-    --xh-_accordion-trigger-font-size: var(--xh-font-size-lg);
+    --xh-_accordion-trigger-font-size: var(--xh-control-font-lg);
   }
 
   [data-scope='accordion'][data-part='item'] {
-    border-block-end: 1px solid var(--xh-accordion-item-border, var(--xh-border-default));
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-accordion-item-border, var(--xh-border-default));
     min-inline-size: 0;
   }
 
@@ -92,17 +100,65 @@
     transition: rotate var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
-  [data-scope='accordion'][data-part='indicator']::before {
-    content: '⌄';
+  /* 没写内容就由皮肤画；作者往部件里塞了自己的图形，这条规则即不命中 */
+  [data-scope='accordion'][data-part='indicator']: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-down) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-down) center / contain no-repeat;
   }
 
   [data-scope='accordion'][data-part='indicator'][data-state='open'] {
     rotate: 180deg;
   }
 
+  /* 这里刻意没有 [data-part='content'][hidden] { display: none }：补了动画一帧都播不出来。
+     收起由适配器在退场结束后写内联 display 落成，退场窗口内靠 connect 发的 inert 挡住焦点 */
   [data-scope='accordion'][data-part='content'] {
+    display: grid;
+    grid-template-rows: 1fr;
+    overflow: clip;
     padding-block: var(--xh-accordion-content-py, var(--xh-stack-gap-md));
     padding-inline: var(--xh-accordion-content-px, var(--xh-control-px-md));
     color: var(--xh-accordion-content-fg, var(--xh-fg-default));
   }
+
+  [data-scope='accordion'][data-part='content'][data-state='open'] {
+    animation: xh-accordion-expand var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='accordion'][data-part='content'][data-state='closed'] {
+    animation: xh-accordion-collapse var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+}
+
+@layer xihan.motion {
+  /* 行高与内缩同帧动：内缩不归零的话，border-box 会把盒子钳在上下内缩之和上，收不干净 */
+  @keyframes xh-accordion-expand {
+    from {
+      grid-template-rows: 0fr;
+      padding-block: 0;
+    }
+
+    to {
+      grid-template-rows: 1fr;
+      padding-block: var(--xh-accordion-content-py, var(--xh-stack-gap-md));
+    }
+  }
+
+  @keyframes xh-accordion-collapse {
+    from {
+      grid-template-rows: 1fr;
+      padding-block: var(--xh-accordion-content-py, var(--xh-stack-gap-md));
+    }
+
+    to {
+      grid-template-rows: 0fr;
+      padding-block: 0;
+    }
+  }
 }

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,5 +1,13 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='alert'] {
+    --xh-alert-skin: 1;
+  }
+
   [data-scope='alert'][data-part='root'] {
+    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-alert-icon-size, var(--xh-glyph-size-text));
+
     /* 强调色随语气走，底色/描边/图标色都由它推导出来，换语气不必逐条属性各写一遍。
        没写 data-tone 时 --xh-_tone 没被声明，退回原来的 info 蓝 */
     --xh-_alert-accent: var(--xh-_tone-soft, var(--xh-color-info-500));
@@ -19,7 +27,7 @@
     border-radius: var(--xh-alert-radius, var(--xh-shape-surface));
     background: var(--xh-alert-bg, var(--xh-_alert-tint));
     color: var(--xh-alert-fg, var(--xh-fg-default));
-    font-size: var(--xh-alert-font-size, var(--xh-font-size-md));
+    font-size: var(--xh-alert-font-size, var(--xh-text-body-size));
     line-height: var(--xh-alert-leading, var(--xh-leading-normal));
   }
 
@@ -35,7 +43,7 @@
     justify-content: center;
     flex: none;
     /* 与首行文字对齐：图标框高取一行正文的行高 */
-    block-size: calc(var(--xh-font-size-md) * var(--xh-leading-normal));
+    block-size: calc(var(--xh-text-body-size) * var(--xh-leading-normal));
     inline-size: var(--xh-alert-icon-size, var(--xh-control-indicator-size));
     color: var(--xh-alert-icon-fg, var(--xh-_alert-accent));
   }
@@ -51,7 +59,7 @@
   [data-scope='alert'][data-part='title'] {
     flex: 1 1 auto;
     color: var(--xh-alert-title-fg, var(--xh-fg-default));
-    font-size: var(--xh-alert-title-font-size, var(--xh-font-size-md));
+    font-size: var(--xh-alert-title-font-size, var(--xh-text-label-size));
     font-weight: var(--xh-alert-title-font-weight, var(--xh-font-weight-semibold));
     line-height: var(--xh-alert-title-leading, var(--xh-leading-tight));
   }
@@ -59,7 +67,7 @@
   [data-scope='alert'][data-part='description'] {
     flex: 1 1 100%;
     color: var(--xh-alert-description-fg, var(--xh-fg-muted));
-    font-size: var(--xh-alert-description-font-size, var(--xh-font-size-sm));
+    font-size: var(--xh-alert-description-font-size, var(--xh-text-secondary-size));
   }
 
   /* 没写标题时说明自己占满这一行，否则它会挤在标题旁边 */
@@ -84,6 +92,10 @@
     font: inherit;
     line-height: var(--xh-leading-none);
     cursor: pointer;
+    transition:
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      scale var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   /* closable=false 时连接层同时给了 hidden 与 disabled，这条是它真正收起的那一半 */
@@ -91,11 +103,17 @@
     display: none;
   }
 
+  /* 悬停与按下的底色跟着语气走：提示本体已是该语气的淡底，叉的底色在同一色系里再深两档 */
   [data-scope='alert'][data-part='close-trigger']:hover:not(:disabled) {
-    background: color-mix(in oklab, var(--xh-_alert-accent) 16%, transparent);
+    background: var(--xh-alert-close-bg-hover, var(--xh-_tone-subtle-hover, var(--xh-bg-subtle-hover)));
     color: var(--xh-alert-close-fg-hover, var(--xh-fg-default));
   }
 
+  [data-scope='alert'][data-part='close-trigger']:active {
+    background: var(--xh-alert-close-bg-active, var(--xh-_tone-subtle-active, var(--xh-bg-subtle-active)));
+    scale: var(--xh-motion-scale-press);
+  }
+
   [data-scope='alert'][data-part='close-trigger']:disabled {
     color: var(--xh-fg-disabled);
     cursor: not-allowed;
@@ -105,4 +123,16 @@
     outline: var(--xh-ring-width) solid var(--xh-ring-focus);
     outline-offset: var(--xh-ring-offset);
   }
+
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
+  [data-scope='alert'][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;
+  }
 }

package/css/anchor.css

@@ -1,10 +1,15 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='anchor'] {
+    --xh-anchor-skin: 1;
+  }
+
   /* 根节点是 nav 地标，不参与排版：整条目录的布局全在 list 上，
      这里不给 display，UA 的 [hidden]{display:none} 就仍然压得住 */
   [data-scope='anchor'][data-part='root'] {
     /* 尺寸档只换这两个私有槽，链接从 root 继承它们，换档不必给每个部件各写一条选择器 */
     --xh-_anchor-font-size: var(--xh-text-label-size);
-    --xh-_anchor-link-px: var(--xh-space-3);
+    --xh-_anchor-link-px: var(--xh-control-px-md);
     /* 当前那一节的指示条与文字随语气走。没写 data-tone 时这两个槽都没被声明，退回原来的品牌色。
        指示条是装饰性的色条，取柔和档；文字要压在普通背景上读，取语气的文字档。
        聚焦环不在其列，它恒是 --xh-ring-focus */
@@ -17,14 +22,14 @@
   }
 
   /* —— 尺寸 —— */
-  /* 缺省档写在上面的基础规则里；链接的内边距走控件内边距那把尺，缺省的 --xh-space-3 即它的中档 */
+  /* 缺省档写在上面的基础规则里；链接的内边距三档都走控件内边距那把尺 */
   [data-scope='anchor'][data-part='root'][data-size='sm'] {
-    --xh-_anchor-font-size: var(--xh-font-size-sm);
+    --xh-_anchor-font-size: var(--xh-control-font-sm);
     --xh-_anchor-link-px: var(--xh-control-px-sm);
   }
 
   [data-scope='anchor'][data-part='root'][data-size='lg'] {
-    --xh-_anchor-font-size: var(--xh-font-size-lg);
+    --xh-_anchor-font-size: var(--xh-control-font-lg);
     --xh-_anchor-link-px: var(--xh-control-px-lg);
   }
 
@@ -71,7 +76,7 @@
     display: inline-flex;
     align-items: center;
     /* 一节的标题可能很长，压不住会把整列撑开 */
-    max-inline-size: var(--xh-anchor-link-max-w, 14rem);
+    max-inline-size: var(--xh-anchor-link-max-w, var(--xh-nav-link-max-w));
     padding-block: var(--xh-anchor-link-py, var(--xh-space-1));
     padding-inline: var(--xh-anchor-link-px, var(--xh-_anchor-link-px));
     border-radius: var(--xh-anchor-link-radius, var(--xh-shape-control));
@@ -98,7 +103,7 @@
 
   /* 当前那一节：颜色与字重都跟着变，不只靠指示条——
      指示条是可选部件，作者不渲染它时"当前在哪"仍然要看得出来 */
-  [data-scope='anchor'][data-part='link'][data-active] {
+  [data-scope='anchor'][data-part='link'][data-current] {
     color: var(--xh-anchor-link-fg-active, var(--xh-_anchor-accent-text));
     font-weight: var(--xh-anchor-link-font-weight-active, var(--xh-font-weight-medium));
   }
@@ -112,7 +117,7 @@
     margin: 0;
     inset-inline-start: calc(var(--xh-anchor-indicator-thickness, var(--xh-stroke-thick)) * -1);
     inline-size: var(--xh-anchor-indicator-thickness, var(--xh-stroke-thick));
-    border-radius: var(--xh-anchor-indicator-radius, var(--xh-radius-full));
+    border-radius: var(--xh-anchor-indicator-radius, var(--xh-shape-pill));
     background: var(--xh-anchor-indicator-color, var(--xh-_anchor-accent));
     transition:
       inset-block-start var(--xh-motion-duration-enter) var(--xh-motion-ease-enter),

package/css/avatar-group.css

@@ -1,10 +1,15 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='avatar-group'] {
+    --xh-avatar-group-skin: 1;
+  }
+
   /* 一排叠放的头像：后一枚压在前一枚上。
      组内共用的直径与字号在容器上写一次，沿继承流给每一枚；自己写了档位的那一枚仍按自己的档走 */
   [data-scope='avatar-group'][data-part='root'] {
     /* 私有槽位：整组共用的直径、字号与叠放量，换档只改这三个 */
     --xh-_avatar-group-size: var(--xh-avatar-group-size, var(--xh-control-h-md));
-    --xh-_avatar-group-font-size: var(--xh-avatar-group-font-size, var(--xh-font-size-sm));
+    --xh-_avatar-group-font-size: var(--xh-avatar-group-font-size, var(--xh-text-secondary-size));
     --xh-_avatar-group-overlap: var(--xh-avatar-group-overlap, var(--xh-space-2_5));
 
     /* 流给组内每一枚 */
@@ -26,13 +31,13 @@
      字号与叠放量跟着直径一起缩放，小头像里回退字放得下、大头像里压住的那段也按比例长 */
   [data-scope='avatar-group'][data-part='root'][data-size='sm'] {
     --xh-_avatar-group-size: var(--xh-avatar-group-size, var(--xh-control-h-sm));
-    --xh-_avatar-group-font-size: var(--xh-avatar-group-font-size, var(--xh-font-size-xs));
+    --xh-_avatar-group-font-size: var(--xh-avatar-group-font-size, var(--xh-control-caption-sm));
     --xh-_avatar-group-overlap: var(--xh-avatar-group-overlap, var(--xh-space-2));
   }
 
   [data-scope='avatar-group'][data-part='root'][data-size='lg'] {
     --xh-_avatar-group-size: var(--xh-avatar-group-size, var(--xh-control-h-lg));
-    --xh-_avatar-group-font-size: var(--xh-avatar-group-font-size, var(--xh-font-size-md));
+    --xh-_avatar-group-font-size: var(--xh-avatar-group-font-size, var(--xh-control-caption-lg));
     --xh-_avatar-group-overlap: var(--xh-avatar-group-overlap, var(--xh-space-3));
   }
 

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;
@@ -11,7 +16,7 @@
     border-radius: var(--xh-avatar-radius, var(--xh-shape-pill));
     background: var(--xh-avatar-bg, var(--xh-bg-subtle));
     color: var(--xh-avatar-fg, var(--xh-fg-muted));
-    font-size: var(--xh-avatar-font-size, var(--xh-font-size-sm));
+    font-size: var(--xh-avatar-font-size, var(--xh-text-secondary-size));
     font-weight: var(--xh-avatar-font-weight, var(--xh-font-weight-medium));
     line-height: var(--xh-leading-none);
     user-select: none;
@@ -22,13 +27,13 @@
   [data-scope='avatar'][data-part='root'][data-size='sm'] {
     inline-size: var(--xh-control-h-sm);
     block-size: var(--xh-control-h-sm);
-    font-size: var(--xh-font-size-xs);
+    font-size: var(--xh-control-caption-sm);
   }
 
   [data-scope='avatar'][data-part='root'][data-size='lg'] {
     inline-size: var(--xh-control-h-lg);
     block-size: var(--xh-control-h-lg);
-    font-size: var(--xh-font-size-md);
+    font-size: var(--xh-control-caption-lg);
   }
 
   /* 不声明 display，加载完成前的 hidden 直接交给浏览器的 [hidden] 规则收起 */

package/css/back-top.css

@@ -1,7 +1,15 @@
 @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'] {
+    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-back-top-icon-size, var(--xh-glyph-size-text));
+
     /* 尺寸档只换这一个私有槽，按钮从壳继承，换档不必给每个部件各写一条选择器 */
     --xh-_back-top-size: var(--xh-control-h-md);
 
@@ -34,7 +42,7 @@
     background: var(--xh-back-top-bg, var(--xh-bg-surface-raised));
     color: var(--xh-back-top-fg, var(--xh-_tone-fg, var(--xh-fg-default)));
     /* 浮在内容之上，靠投影与页面拉开层次 */
-    box-shadow: var(--xh-elevation-2);
+    box-shadow: var(--xh-back-top-shadow, var(--xh-elevation-sheet));
     cursor: pointer;
     transition:
       background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
@@ -58,4 +66,16 @@
     outline: var(--xh-ring-width) solid var(--xh-ring-focus);
     outline-offset: var(--xh-ring-offset);
   }
+
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
+  [data-scope='back-top'][data-part='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-up) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-up) center / contain no-repeat;
+  }
 }

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;
@@ -9,12 +14,26 @@
     border-radius: var(--xh-shape-pill);
     background: var(--xh-badge-bg, var(--xh-bg-subtle));
     color: var(--xh-badge-fg, var(--xh-fg-default));
-    font-size: var(--xh-badge-font-size, var(--xh-font-size-xs));
+    font-size: var(--xh-badge-font-size, var(--xh-text-caption-size));
     font-weight: var(--xh-badge-font-weight, var(--xh-font-weight-medium));
     line-height: var(--xh-leading-none);
     white-space: nowrap;
   }
 
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     计数为 0 且没开 showZero 时连接层会发 hidden */
+  [data-scope='badge'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 圆点形态：只表示「有」，不表示「有几个」——收掉内边距与文字盒 */
+  [data-scope='badge'][data-part='root'][data-dot] {
+    inline-size: var(--xh-badge-dot-size, var(--xh-space-2));
+    block-size: var(--xh-badge-dot-size, var(--xh-space-2));
+    padding: 0;
+    font-size: 0;
+  }
+
   /* —— 变体 —— */
   /* 形态只决定颜色怎么用；用哪族颜色由 data-tone 决定，没写 tone 就沿用原来的品牌/中性配色 */
   [data-scope='badge'][data-part='root'][data-variant='solid'] {
@@ -45,6 +64,6 @@
     gap: var(--xh-space-1_5);
     padding-inline: var(--xh-space-3);
     padding-block: var(--xh-space-1);
-    font-size: var(--xh-font-size-sm);
+    font-size: var(--xh-text-secondary-size);
   }
 }

package/css/breadcrumb.css

@@ -1,7 +1,15 @@
 @layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='breadcrumb'] {
+    --xh-breadcrumb-skin: 1;
+  }
+
   /* 根节点是 nav 地标，不参与排版：整条路径的行为全在 list 上，
      这里不给 display，UA 的 [hidden]{display:none} 就仍然压得住 */
   [data-scope='breadcrumb'][data-part='root'] {
+    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-breadcrumb-icon-size, var(--xh-glyph-size-text));
+
     /* 尺寸档只换这两个私有槽，列表与链接都从 root 继承它们，换档不必给每个部件各写一条选择器 */
     --xh-_breadcrumb-font-size: var(--xh-text-label-size);
     --xh-_breadcrumb-gap: var(--xh-space-2);
@@ -18,12 +26,12 @@
   /* 缺省档写在上面的基础规则里。间距量的是路径里文字与分隔符之间的距离，
      不在控件间距那把尺上（那把尺的大档与中档同值），三档一律取空间尺 */
   [data-scope='breadcrumb'][data-part='root'][data-size='sm'] {
-    --xh-_breadcrumb-font-size: var(--xh-font-size-sm);
+    --xh-_breadcrumb-font-size: var(--xh-control-font-sm);
     --xh-_breadcrumb-gap: var(--xh-space-1_5);
   }
 
   [data-scope='breadcrumb'][data-part='root'][data-size='lg'] {
-    --xh-_breadcrumb-font-size: var(--xh-font-size-lg);
+    --xh-_breadcrumb-font-size: var(--xh-control-font-lg);
     --xh-_breadcrumb-gap: var(--xh-space-3);
   }
 
@@ -61,7 +69,7 @@
     align-items: center;
     gap: var(--xh-breadcrumb-link-gap, var(--xh-space-1));
     /* 一层的名字可能很长（文档标题、订单号），压不住会把整条路径撑开 */
-    max-inline-size: var(--xh-breadcrumb-link-max-w, 12rem);
+    max-inline-size: var(--xh-breadcrumb-link-max-w, var(--xh-nav-link-max-w));
     padding-inline: var(--xh-breadcrumb-link-px, var(--xh-space-1));
     border-radius: var(--xh-breadcrumb-link-radius, var(--xh-shape-control));
     color: inherit;
@@ -117,11 +125,28 @@
 
   /* 分隔符常常是个图标：给一个跟着字号走的方框，斜杠与图标混用时基线才不跳 */
   [data-scope='breadcrumb'][data-part='separator'] {
-    inline-size: var(--xh-breadcrumb-separator-size, 1em);
+    inline-size: var(--xh-breadcrumb-separator-size, var(--xh-glyph-size-text));
   }
 
   [data-scope='breadcrumb'][data-part='ellipsis'] {
     inline-size: var(--xh-breadcrumb-ellipsis-size, var(--xh-space-5));
     cursor: default;
   }
+
+  /* 没写内容就由皮肤画兜底字形（向前的尖角）；作者写了斜杠或自己的图形，这条即不命中 */
+  [data-scope='breadcrumb'][data-part='separator']: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;
+  }
+
+  /* 从右往左排版时「向前」在左边 */
+  [dir='rtl'] [data-scope='breadcrumb'][data-part='separator']:empty::before {
+    rotate: 180deg;
+  }
 }

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，组内每段都取得到，两端的圆角再逐段补回来 */
@@ -25,26 +30,27 @@
 
   /* —— 尺寸 —— */
   /* 高度、内边距、间距、字号在容器上写一次，沿继承流给组内每一段。
-     三档都写出来：自定义属性会一路继承，组里再套一组时内层不写就会沿用外层的档 */
+     三档都写出来：自定义属性会一路继承，组里再套一组时内层不写就会沿用外层的档。
+     写私有槽而非 --xh-button-*：后者是使用者的入口，组内某一枚自己写了档位时要压得住容器 */
   [data-scope='button-group'][data-part='root'][data-size='sm'] {
-    --xh-button-h: var(--xh-control-h-sm);
-    --xh-button-px: var(--xh-control-px-sm);
-    --xh-button-gap: var(--xh-control-gap-sm);
-    --xh-button-font-size: var(--xh-font-size-sm);
+    --xh-_button-group-h: var(--xh-control-h-sm);
+    --xh-_button-group-px: var(--xh-control-px-sm);
+    --xh-_button-group-gap: var(--xh-control-gap-sm);
+    --xh-_button-group-font-size: var(--xh-control-font-sm);
   }
 
   [data-scope='button-group'][data-part='root'][data-size='md'] {
-    --xh-button-h: var(--xh-control-h-md);
-    --xh-button-px: var(--xh-control-px-md);
-    --xh-button-gap: var(--xh-control-gap-md);
-    --xh-button-font-size: var(--xh-font-size-md);
+    --xh-_button-group-h: var(--xh-control-h-md);
+    --xh-_button-group-px: var(--xh-control-px-md);
+    --xh-_button-group-gap: var(--xh-control-gap-md);
+    --xh-_button-group-font-size: var(--xh-control-font-md);
   }
 
   [data-scope='button-group'][data-part='root'][data-size='lg'] {
-    --xh-button-h: var(--xh-control-h-lg);
-    --xh-button-px: var(--xh-control-px-lg);
-    --xh-button-gap: var(--xh-control-gap-lg);
-    --xh-button-font-size: var(--xh-font-size-lg);
+    --xh-_button-group-h: var(--xh-control-h-lg);
+    --xh-_button-group-px: var(--xh-control-px-lg);
+    --xh-_button-group-gap: var(--xh-control-gap-lg);
+    --xh-_button-group-font-size: var(--xh-control-font-lg);
   }
 
   /* —— 形态 —— */

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));
@@ -6,17 +21,21 @@
     --xh-_bg-active: var(--xh-button-bg-active, var(--xh-bg-subtle-active));
     --xh-_fg: var(--xh-button-fg, var(--xh-fg-default));
 
+    /* 作者塞进来的图标跟着按钮的尺寸档走：xh-icon 的直径读的就是这个继承槽，
+       它自己显式写了 size 时特异性更高，仍以作者写的为准 */
+    --xh-icon-size: var(--xh-button-icon-size, var(--xh-glyph-size-md));
+
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    gap: var(--xh-button-gap, var(--xh-control-gap-md));
-    block-size: var(--xh-button-h, var(--xh-control-h-md));
-    padding-inline: var(--xh-button-px, var(--xh-control-px-md));
+    gap: var(--xh-button-gap, var(--xh-_button-group-gap, var(--xh-control-gap-md)));
+    block-size: var(--xh-button-h, var(--xh-_button-group-h, var(--xh-control-h-md)));
+    padding-inline: var(--xh-button-px, var(--xh-_button-group-px, var(--xh-control-px-md)));
     border: var(--xh-stroke-thin) solid transparent;
     border-radius: var(--xh-button-radius, var(--xh-shape-control));
     background: var(--xh-_bg);
     color: var(--xh-_fg);
-    font-size: var(--xh-button-font-size, var(--xh-text-label-size));
+    font-size: var(--xh-button-font-size, var(--xh-_button-group-font-size, var(--xh-text-label-size)));
     font-weight: var(--xh-button-font-weight, var(--xh-text-label-weight));
     line-height: var(--xh-leading-none);
     white-space: nowrap;
@@ -80,19 +99,46 @@
 
   /* —— 尺寸 —— */
   [data-scope='button'][data-part='root'][data-size='sm'] {
-    block-size: var(--xh-control-h-sm);
-    padding-inline: var(--xh-control-px-sm);
-    font-size: var(--xh-font-size-sm);
+    --xh-icon-size: var(--xh-button-icon-size, var(--xh-glyph-size-sm));
+
+    block-size: var(--xh-button-h, var(--xh-control-h-sm));
+    padding-inline: var(--xh-button-px, var(--xh-control-px-sm));
+    font-size: var(--xh-button-font-size, var(--xh-control-font-sm));
   }
 
   [data-scope='button'][data-part='root'][data-size='lg'] {
-    block-size: var(--xh-control-h-lg);
-    padding-inline: var(--xh-control-px-lg);
-    font-size: var(--xh-font-size-lg);
+    --xh-icon-size: var(--xh-button-icon-size, var(--xh-glyph-size-lg));
+
+    block-size: var(--xh-button-h, var(--xh-control-h-lg));
+    padding-inline: var(--xh-button-px, var(--xh-control-px-lg));
+    font-size: var(--xh-button-font-size, var(--xh-control-font-lg));
+  }
+
+  /* 只有图标：左右内距清零，宽度靠比例跟住当前档的高度——换尺寸档时仍是正方形，
+     不必把档位抄进行内样式。写在尺寸档之后，压得住三档各自的 padding-inline */
+  [data-scope='button'][data-part='root'][data-icon-only] {
+    padding-inline: 0;
+    aspect-ratio: 1;
+  }
+
+  [data-scope='button'][data-part='root'][data-full-width] {
+    inline-size: 100%;
   }
 
   [data-scope='button'][data-part='indicator'] {
     display: inline-flex;
-    animation: xh-spin 0.6s linear infinite;
+    animation: xh-spin var(--xh-button-spin-duration, var(--xh-spin-duration)) linear infinite;
+  }
+
+  /* 减少动效：指示器停转，"还在忙"由按钮自身的挂起样式与指示器图标继续表达。
+     两条规则是同一件事的两个触发条件：系统偏好与作者打的 data-motion */
+  @media (prefers-reduced-motion: reduce) {
+    [data-scope='button'][data-part='indicator'] {
+      animation: none;
+    }
+  }
+
+  :where([data-motion='reduce']) [data-scope='button'][data-part='indicator'] {
+    animation: none;
   }
 }