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

package/css/thread.css

@@ -7,6 +7,10 @@
   /* 自建定位上下文，作为绝对定位的回到底部按钮的参照系；
      block-size: 100% 让高度由外部决定，使滚动发生在内部。 */
   [data-scope='thread'][data-part='root'] {
+    /* 组件内那几档层号只在自己人之间排序：建一个层叠上下文把它们关起来，
+       既不让页面上的层号插进来，也不让它们漏出去压住别人 */
+    isolation: isolate;
+
     position: relative;
     display: flex;
     flex-direction: column;
@@ -20,14 +24,18 @@
 
   /* 滚动容器，粘底读的是它的 scrollTop / clientHeight / scrollHeight。
      min-block-size: 0 让弹性子项能被压缩从而触发溢出；
-     overscroll-behavior: contain 阻止滚动量传给页面；
-     scrollbar-gutter: stable 避免滚动条出现与消失时推动文字。 */
+     overscroll-behavior: contain 阻止滚动量传给页面。 */
   [data-scope='thread'][data-part='viewport'] {
     flex: 1;
     min-block-size: 0;
     /* 逻辑属性 overflow-block 尚无可用实现，写物理轴 */
     overflow-y: auto;
     overscroll-behavior: contain;
+  }
+
+  /* 还在用原生滚动条的视口留一条空道，滚动条出现与消失时不推动文字。
+     带 data-xh-scrollbar 的容器已经把原生条藏成零宽，这条空道对它没有布局作用，排除掉 */
+  [data-scope='thread'][data-part='viewport']:not([data-xh-scrollbar]) {
     scrollbar-gutter: stable;
   }
 

package/css/time-field.css

@@ -13,8 +13,8 @@
     --xh-_time-field-control-h: var(--xh-control-h-md);
     --xh-_time-field-control-px: var(--xh-control-px-md);
     --xh-_time-field-gap: var(--xh-control-gap-md);
-    --xh-_time-field-font-size: var(--xh-text-body-size);
-    --xh-_time-field-label-font-size: var(--xh-text-label-size);
+    --xh-_time-field-font-size: var(--xh-control-font-md);
+    --xh-_time-field-label-font-size: var(--xh-control-font-md);
     /* 形态档只换这三个私有槽：底色与两档描边 */
     --xh-_time-field-control-bg: var(--xh-bg-canvas);
     --xh-_time-field-control-border: var(--xh-border-control);

package/css/time-picker.css

@@ -24,8 +24,8 @@
     --xh-_time-picker-control-h: var(--xh-control-h-md);
     --xh-_time-picker-control-px: var(--xh-control-px-md);
     --xh-_time-picker-gap: var(--xh-control-gap-md);
-    --xh-_time-picker-font-size: var(--xh-text-body-size);
-    --xh-_time-picker-label-font-size: var(--xh-text-label-size);
+    --xh-_time-picker-font-size: var(--xh-control-font-md);
+    --xh-_time-picker-label-font-size: var(--xh-control-font-md);
     --xh-_time-picker-item-px: var(--xh-control-px-md);
 
     /* 形态档只换这三个私有槽：底色与两档描边 */
@@ -342,7 +342,7 @@
     display: flex;
     flex: none;
     flex-direction: column;
-    gap: var(--xh-time-picker-presets-gap, var(--xh-space-0_5));
+    gap: var(--xh-time-picker-presets-gap, var(--xh-list-option-gap));
     max-block-size: var(--xh-time-picker-presets-h, var(--xh-viewport-h-sm));
     padding-inline: var(--xh-time-picker-presets-px, var(--xh-space-1));
     overflow-y: auto;
@@ -357,7 +357,7 @@
   [data-scope='time-picker'][data-part='preset'] {
     padding-block: var(--xh-time-picker-preset-py, var(--xh-space-1));
     padding-inline: var(--xh-time-picker-preset-px, var(--xh-space-3));
-    border-radius: var(--xh-shape-control);
+    border-radius: var(--xh-time-picker-preset-radius, var(--xh-shape-control));
     font-size: var(--xh-text-secondary-size);
     line-height: var(--xh-leading-normal);
     white-space: nowrap;
@@ -397,7 +397,7 @@
     display: flex;
     flex: none;
     flex-direction: column;
-    gap: var(--xh-time-picker-column-gap, var(--xh-space-0_5));
+    gap: var(--xh-time-picker-column-gap, var(--xh-list-option-gap));
     min-inline-size: var(--xh-time-picker-column-min-w, 3.5rem);
     /* 几列并排：定高而不是随内容收，否则时列与分列的可选值一多一少就错位 */
     block-size: var(--xh-time-picker-column-h, var(--xh-viewport-h-sm));
@@ -432,7 +432,7 @@
     flex: none;
     align-items: center;
     justify-content: center;
-    padding-block: var(--xh-time-picker-item-py, var(--xh-space-1_5));
+    padding-block: var(--xh-time-picker-item-py, var(--xh-list-option-py-md));
     padding-inline: var(--xh-time-picker-item-px, var(--xh-_time-picker-item-px));
     border-radius: var(--xh-time-picker-item-radius, var(--xh-shape-control));
     color: var(--xh-time-picker-item-fg, var(--xh-fg-default));

package/css/timeline.css

@@ -10,7 +10,7 @@
     --xh-_timeline-dot-size: var(--xh-space-2_5);
     --xh-_timeline-gutter: var(--xh-space-3);
     --xh-_timeline-item-gap: var(--xh-space-5);
-    --xh-_timeline-title-font-size: var(--xh-text-label-size);
+    --xh-_timeline-title-font-size: var(--xh-control-font-md);
     --xh-_timeline-caption-font-size: var(--xh-text-caption-size);
     /* 标题首行占多高。圆点按它居中下移，圆心才落在标题这一行的中线上 */
     --xh-_timeline-line-h: calc(
@@ -92,7 +92,7 @@
     justify-content: center;
     inline-size: var(--xh-timeline-indicator-size, var(--xh-_timeline-dot-size));
     block-size: var(--xh-timeline-indicator-size, var(--xh-_timeline-dot-size));
-    border-radius: var(--xh-shape-pill);
+    border-radius: var(--xh-timeline-indicator-radius, var(--xh-shape-pill));
     /* 使用者令牌排在语气之前；两者都没有时退回一个中性的实心点 */
     background: var(--xh-timeline-indicator-bg, var(--xh-_tone-soft, var(--xh-fg-muted)));
     color: var(--xh-timeline-indicator-fg, var(--xh-_tone-on, var(--xh-fg-on-brand)));
@@ -120,7 +120,7 @@
 
   /* —— 连线 —— */
   [data-scope='timeline'][data-part='connector'] {
-    border-radius: var(--xh-shape-pill);
+    border-radius: var(--xh-timeline-connector-radius, var(--xh-shape-pill));
     background: var(--xh-timeline-connector-bg, var(--xh-border-default));
   }
 
@@ -158,7 +158,7 @@
   [data-scope='timeline'][data-part='content'] {
     display: flex;
     flex-direction: column;
-    gap: var(--xh-space-1);
+    gap: var(--xh-timeline-content-gap, var(--xh-space-1));
     min-inline-size: 0;
   }
 
@@ -176,7 +176,7 @@
   [data-scope='timeline'][data-part='item'][data-orientation='horizontal'] [data-scope='timeline'][data-part='content'] {
     grid-column: 1 / -1;
     grid-row: 2;
-    padding-block-start: var(--xh-space-2);
+    padding-block-start: var(--xh-timeline-content-pt, var(--xh-space-2));
     padding-inline-end: var(--xh-timeline-item-gap, var(--xh-_timeline-item-gap));
   }
 
@@ -241,7 +241,7 @@
     grid-row: 1;
     align-self: end;
     padding-block-start: 0;
-    padding-block-end: var(--xh-space-2);
+    padding-block-end: var(--xh-timeline-content-pb, var(--xh-space-2));
   }
 
   [data-scope='timeline'][data-part='item'][data-orientation='horizontal'][data-placement='alternate'] {
@@ -262,7 +262,7 @@
     grid-row: 1;
     align-self: end;
     padding-block-start: 0;
-    padding-block-end: var(--xh-space-2);
+    padding-block-end: var(--xh-timeline-content-pb, var(--xh-space-2));
   }
 
   /* —— 文字 —— */

package/css/toast.css

@@ -1,8 +1,8 @@
 @layer xihan.motion {
   /*
-   * 九个位共用同一条进出场，位移不跟着落位走：要按位置分方向，就得从 toaster 的
-   * data-placement 反向选到卡片上，等于把一个组件的动效写进另一个组件的选择器里，
-   * 两边任意一侧改名都会静默失效。竖向一小段位移在九个位上都说得通。
+   * 九个位共用同一条进出场，位移不跟着落位走：要按位置分方向就得从摞的
+   * data-placement 反向选到条子上，落位一改名整条动效静默失效。
+   * 竖向一小段位移在九个位上都说得通。
    */
   @keyframes xh-toast-in {
     from {
@@ -39,45 +39,95 @@
     --xh-toast-skin: 1;
   }
 
+  /*
+   * 一摞 = 一整面视口大小的定位面：贴边靠 padding，落位靠 justify/align 表达。
+   * 不用四角 inset 逐个摆，是因为 column flex 的 align-items 走的是行内轴，
+   * RTL 下 start/end 自动跟着翻；写死 inset-inline-start 的话居中那三个位
+   * 还得再配一次 translate，方向一变就错。
+   * 摞由全局服务渲染，没有对应的容器组件——一次操作的反馈落在哪儿是整个服务的口径。
+   */
+  [data-scope='toast'][data-part='group'] {
+    position: fixed;
+    inset-block: 0;
+    inset-inline: 0;
+    z-index: var(--xh-toast-layer, var(--xh-layer-toast));
+    display: flex;
+    flex-direction: column;
+    /* 基线按默认落位 top 写，下面只覆盖跟它不同的那几个位 */
+    justify-content: flex-start;
+    align-items: center;
+    padding-block: var(--xh-toast-inset, var(--xh-space-6));
+    padding-inline: var(--xh-toast-inset, var(--xh-space-6));
+    /* 摞内间距由服务写进内联 style，这里绝不重复写：
+       写了也会被内联盖掉，只会让人误以为间距归样式层管 */
+    /* 整面铺开就等于罩住了整块视口。面本身不吃指针，只有条子吃（见下），
+       否则底下的页面就再也点不动了 */
+    pointer-events: none;
+  }
+
+  [data-scope='toast'][data-part='group'][hidden] {
+    display: none;
+  }
+
+  /* 块轴落位：^= 一次吃掉某一行的三个位（top / top-start / top-end） */
+  [data-scope='toast'][data-part='group'][data-placement^='middle'] {
+    justify-content: center;
+  }
+
+  [data-scope='toast'][data-part='group'][data-placement^='bottom'] {
+    justify-content: flex-end;
+  }
+
+  /* 行内轴落位：不带后缀的 top / middle / bottom 用基线的居中 */
+  [data-scope='toast'][data-part='group'][data-placement$='-start'] {
+    align-items: flex-start;
+  }
+
+  [data-scope='toast'][data-part='group'][data-placement$='-end'] {
+    align-items: flex-end;
+  }
+
+  /*
+   * 一条轻提示是「一句话 + 一枚状态字形」，横排一行、贴着文字收缩。
+   * 语气由淡底、描边与字形三者一起承载，正文留中性——正文也跟着兑成语气色的话，
+   * 绿字压在绿底上，对比度是整条里最差的那一处。
+   */
   [data-scope='toast'][data-part='root'] {
-    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
-    --xh-icon-size: var(--xh-toast-icon-size, var(--xh-glyph-size-text));
+    /* 状态字形按控件指示符那一档走，与 alert 的图标框同一把尺 */
+    --xh-icon-size: var(--xh-toast-icon-size, var(--xh-control-indicator-size));
+
+    /* 底与描边取语气层派生好的槽，不在这儿自己再兑一遍：
+       兑法差一档，字形压上去的对比度就跟着差一档（alert 踩过这个坑） */
+    --xh-_toast-tint: var(--xh-_tone-subtle);
+    --xh-_toast-edge: var(--xh-_tone-border);
 
     display: flex;
-    flex-direction: column;
-    gap: var(--xh-toast-gap, var(--xh-space-1));
-    inline-size: var(--xh-toast-w, var(--xh-overlay-max-w));
+    align-items: center;
+    gap: var(--xh-toast-gap, var(--xh-control-gap-md));
+    /* 收缩包裹：一句「已保存」撑成定宽方块，右边那片空白会让它读起来像一张公告卡 */
+    inline-size: var(--xh-toast-w, auto);
     /* 摞是整面视口宽的定位面且带内边距，取 100% 就等于自动让出两侧留白，
-       窄屏上不必再算一遍 viewport 减法 */
-    max-inline-size: 100%;
-    padding-block: var(--xh-toast-py, var(--xh-surface-py-sm));
+       窄屏上不必再算一遍 viewport 减法；再叠一道绝对上限，免得一条长文案铺成横幅 */
+    max-inline-size: min(var(--xh-overlay-max-w-xl), 100%);
+    /* 纵内衬取控件档而不是面档：面档（12px）叠上 21px 行盒与两道细边就是 47px 高，
+       那是卡片的体量；控件档（8px）落在 39px，与短消息该有的高度一致
+       （带叉 42px、带操作钮 46px，那两档本就不是默认排版） */
+    padding-block: var(--xh-toast-py, var(--xh-field-py));
     padding-inline: var(--xh-toast-px, var(--xh-surface-px-sm));
-    border: var(--xh-stroke-thin) solid var(--xh-toast-border, var(--xh-border-default));
-    /* 语气色条做成起始侧的粗边，而不是伪元素：圆角与阴影都不用再对第二遍。
-       两条必须排在 border 简写之后，否则被简写重置回细边与常规描边色。
-       颜色由 connect 从 type 派生的 data-tone 经语气层给出，作者写 --xh-toast-accent
-       就能把某一条整体改色；两者都没有时退回原来的 info 蓝 */
-    border-inline-start-width: var(--xh-toast-accent-width, var(--xh-space-1));
-    border-inline-start-color: var(--xh-toast-accent, var(--xh-_tone-soft, var(--xh-color-info-500)));
+    border: var(--xh-stroke-thin) solid var(--xh-toast-border, var(--xh-_toast-edge));
     border-radius: var(--xh-toast-radius, var(--xh-shape-surface));
-    background: var(--xh-toast-bg, var(--xh-bg-surface-raised));
+    background: var(--xh-toast-bg, var(--xh-_toast-tint));
     color: var(--xh-toast-fg, var(--xh-fg-default));
     box-shadow: var(--xh-toast-shadow, var(--xh-elevation-sheet));
-    font-size: var(--xh-toast-font-size, var(--xh-text-secondary-size));
-    line-height: var(--xh-toast-leading, var(--xh-leading-normal));
-    /* 摞的定位面整面铺开且不吃指针，卡片必须自己吃回来：
+    font-size: var(--xh-toast-font-size, var(--xh-text-body-size));
+    line-height: var(--xh-toast-leading, var(--xh-text-body-leading));
+    /* 摞的定位面整面铺开且不吃指针，条子必须自己吃回来：
        悬停按住计时、按钮可点、焦点进出，全指着这一条 */
     pointer-events: auto;
   }
 
-  /* loading 说的是「事情还没完」，不是好消息也不是坏消息，走中性灰。
-     它不是语气：连接层给它派生的 neutral 档是 500，而这里要的是 fg-muted（600） */
-  [data-scope='toast'][data-part='root'][data-type='loading'] {
-    border-inline-start-color: var(--xh-toast-accent, var(--xh-fg-muted));
-  }
-
   /* 退场窗口走完连接层给的是 hidden 属性，而上面声明了 display——
-     漏掉这条，已经"卸载"的通知会一直杵在屏幕上，且再也没人来收 */
+     漏掉这条，已经"卸载"的提示会一直杵在屏幕上，且再也没人来收 */
   [data-scope='toast'][data-part='root'][hidden] {
     display: none;
   }
@@ -88,41 +138,39 @@
   }
 
   /* forwards 不能省：退场窗口（removeDelay 默认 200ms）比退场动画长，
-     不定住末帧的话动画跑完会弹回全不透明，卡片在被收起前先闪一下 */
+     不定住末帧的话动画跑完会弹回全不透明，条子在被收起前先闪一下 */
   [data-scope='toast'][data-part='root'][data-state='dismissing'] {
     animation: xh-toast-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   [data-scope='toast'][data-part='title'] {
-    /* 作者可能把它写成 h2/p，外边距得先归零，否则卡片内的行距对不上 */
+    /* 作者可能把它写成 h2/p，外边距得先归零，否则条子内的行距对不上 */
     margin: 0;
+    /* 吃掉剩余宽度，把操作钮与叉推到行尾；min-inline-size 让它在撞上宽度上限时能换行，
+       flex 项的 min-width 默认是 auto，不归零的话长文案会把条子顶出上限 */
+    flex: 1 1 auto;
+    min-inline-size: 0;
     color: var(--xh-toast-title-fg, var(--xh-fg-default));
-    font-size: var(--xh-toast-title-font-size, var(--xh-text-label-size));
-    font-weight: var(--xh-toast-title-font-weight, var(--xh-font-weight-semibold));
-    line-height: var(--xh-toast-title-leading, var(--xh-leading-tight));
-  }
-
-  [data-scope='toast'][data-part='description'] {
-    margin: 0;
-    color: var(--xh-toast-description-fg, var(--xh-fg-muted));
-    font-size: var(--xh-toast-description-font-size, var(--xh-text-secondary-size));
+    /* 与条子同字号同行高、不加粗：加粗是"这是标题、下面还有正文"的信号，
+       而轻提示没有正文——那一层是 notification 的 */
+    font-size: var(--xh-toast-title-font-size, var(--xh-text-body-size));
+    font-weight: var(--xh-toast-title-font-weight, var(--xh-text-body-weight));
+    line-height: var(--xh-toast-title-leading, var(--xh-text-body-leading));
   }
 
-  /* 没给文案的那一个仍然要留在 DOM 里（aria-labelledby / aria-describedby 指着它），
-     但空盒子会照吃一份 gap，卡片看着就多出一截莫名的留白 */
-  [data-scope='toast'][data-part='title']:empty,
-  [data-scope='toast'][data-part='description']:empty {
+  /* 没给文案时仍然要留在 DOM 里（aria-labelledby 指着它），
+     但空盒子会照吃一份 gap，条子看着就多出一截莫名的留白 */
+  [data-scope='toast'][data-part='title']:empty {
     display: none;
   }
 
-  [data-scope='toast'][data-part='title'][hidden],
-  [data-scope='toast'][data-part='description'][hidden] {
+  [data-scope='toast'][data-part='title'][hidden] {
     display: none;
   }
 
   [data-scope='toast'][data-part='action-trigger'] {
-    /* 作为卡片直接子元素时不跟着拉满整行；被作者包进一行里时它只影响交叉轴，无副作用 */
-    align-self: flex-start;
+    /* 条子是单行 flex，按钮不参与伸缩：文案长了该换行的是文字，不是把按钮压扁 */
+    flex: none;
     display: inline-flex;
     align-items: center;
     justify-content: center;
@@ -132,7 +180,7 @@
     border-radius: var(--xh-toast-action-radius, var(--xh-shape-control));
     background: var(--xh-toast-action-bg, var(--xh-bg-subtle));
     color: var(--xh-toast-action-fg, var(--xh-fg-default));
-    /* 按钮不继承字族字号，不接回来的话卡片里会突然冒出一段系统 UI 字体 */
+    /* 按钮不继承字族字号，不接回来的话条子里会突然冒出一段系统 UI 字体 */
     font: inherit;
     font-weight: var(--xh-toast-action-font-weight, var(--xh-font-weight-medium));
     line-height: var(--xh-leading-none);
@@ -157,14 +205,16 @@
   }
 
   [data-scope='toast'][data-part='close-trigger'] {
-    align-self: flex-start;
-    /* 和操作按钮同处一行时把叉推到行尾；单独作为卡片子元素时则贴到行内末侧 */
+    flex: none;
+    /* 推到行内末侧；和操作按钮同处一行时排在它后面 */
     margin-inline-start: auto;
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    block-size: var(--xh-toast-close-size, var(--xh-control-h-sm));
-    inline-size: var(--xh-toast-close-size, var(--xh-control-h-sm));
+    /* 行级动作钮那一档（24px），不是浮层角落钮的 28px：
+       后者比一行正文的行盒还高，单它就把整条顶高一截 */
+    block-size: var(--xh-toast-close-size, var(--xh-control-action-size));
+    inline-size: var(--xh-toast-close-size, var(--xh-control-action-size));
     border: 0;
     border-radius: var(--xh-toast-close-radius, var(--xh-shape-control));
     background: transparent;

package/css/toggle-group.css

@@ -7,10 +7,36 @@
   /* 分段控件：段与段之间不留缝，靠共边连成一体，所以 root 不设 gap。
      排布只能读 data-orientation——aria-orientation 在多选模式下连接层根本不输出（role=group 不收） */
   [data-scope='toggle-group'][data-part='root'] {
+    /* 组件内那几档层号只在自己人之间排序：建一个层叠上下文把它们关起来，
+       既不让页面上的层号插进来，也不让它们漏出去压住别人 */
+    isolation: isolate;
+
+    /* 段的度量与字号走私有槽中转，与同族的分段控件一处对一处 */
+    --xh-_toggle-group-h: var(--xh-control-h-md);
+    --xh-_toggle-group-px: var(--xh-control-px-md);
+    --xh-_toggle-group-gap: var(--xh-control-gap-md);
+    --xh-_toggle-group-font-size: var(--xh-control-font-md);
+
     display: inline-flex;
     align-items: stretch;
   }
 
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  [data-scope='toggle-group'][data-part='root'][data-size='sm'] {
+    --xh-_toggle-group-h: var(--xh-control-h-sm);
+    --xh-_toggle-group-px: var(--xh-control-px-sm);
+    --xh-_toggle-group-gap: var(--xh-control-gap-sm);
+    --xh-_toggle-group-font-size: var(--xh-control-font-sm);
+  }
+
+  [data-scope='toggle-group'][data-part='root'][data-size='lg'] {
+    --xh-_toggle-group-h: var(--xh-control-h-lg);
+    --xh-_toggle-group-px: var(--xh-control-px-lg);
+    --xh-_toggle-group-gap: var(--xh-control-gap-lg);
+    --xh-_toggle-group-font-size: var(--xh-control-font-lg);
+  }
+
   [data-scope='toggle-group'][data-part='root'][data-orientation='horizontal'] {
     flex-direction: row;
   }
@@ -45,15 +71,15 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    gap: var(--xh-toggle-group-item-gap, var(--xh-control-gap-md));
-    block-size: var(--xh-toggle-group-item-h, var(--xh-control-h-md));
-    padding-inline: var(--xh-toggle-group-item-px, var(--xh-control-px-md));
+    gap: var(--xh-toggle-group-item-gap, var(--xh-_toggle-group-gap));
+    block-size: var(--xh-toggle-group-item-h, var(--xh-_toggle-group-h));
+    padding-inline: var(--xh-toggle-group-item-px, var(--xh-_toggle-group-px));
     border: var(--xh-stroke-thin) solid var(--xh-_border);
     /* 中间段一律直角，圆角只由首末两端补回来 */
     border-radius: 0;
     background: var(--xh-_bg);
     color: var(--xh-_fg);
-    font-size: var(--xh-toggle-group-item-font-size, var(--xh-text-label-size));
+    font-size: var(--xh-toggle-group-item-font-size, var(--xh-_toggle-group-font-size));
     font-weight: var(--xh-toggle-group-item-font-weight, var(--xh-text-label-weight));
     line-height: var(--xh-leading-none);
     white-space: nowrap;

package/css/toggle.css

@@ -105,4 +105,10 @@
     padding-inline: var(--xh-toggle-px, var(--xh-control-px-lg));
     font-size: var(--xh-toggle-font-size, var(--xh-control-font-lg));
   }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  [data-scope='toggle'][data-part='root'][hidden] {
+    display: none;
+  }
 }

package/css/tone.css

@@ -9,19 +9,25 @@
  * 这里只声明私有槽，各组件的形态规则去消费。所以加一个语气是改这一处 6 条规则，
  * 而不是逐个组件写 6 遍。
  *
- * --xh-_tone-on 是实心底上的前景色，按实测对比度分派而非统一白字：
- * 600 档上白字对 brand 5.08、neutral 7.80、danger 4.83 达标，而 success 3.04、
- * warning 2.70、info 3.47 都不到 4.5，这三族必须配深字。
+ * --xh-_tone-on 是实心底上的前景色，--xh-_tone-shift 是交互态要往哪个方向挪
+ * （永远背离前景色走，悬停与按下才不会反过来压低对比度）。两者都由 --xh-_tone 现推：
+ * 按 WCAG 的权重算出语气色的相对亮度，低于 0.179 配白字、高于配深字，shift 取反面。
+ * 0.179 是白字与黑字对比度相等的那一点，解析解。
  *
- * --xh-_tone-shift 是交互态要往哪个方向挪：永远背离前景色走，悬停与按下才不会
- * 反过来压低对比度。白字族往深处挪，深字族往浅处挪。
+ * 现推是因为语气色可换肤：写死的分派只对本仓这套 600 档成立，使用者换一套调色板
+ * 配对就不再成立，而门禁只验本仓的色，换肤后的失配一路绿灯。
  *
- * 这两个槽用的都是固定原语而不是 --xh-fg-default：实心底本身是原语色、不随主题翻，
- * 配色若跟着主题翻，暗色下就会变成白字压在浅黄底上（实测对比度 2.70）。
+ * 够不到相对颜色语法的引擎退回逐族写死的那一份，取值是本仓这套色的实测结果：
+ * 600 档上白字对 brand 5.08、neutral 7.80、danger 4.83 达标，而 success 3.04、
+ * warning 2.70、info 3.47 都不到 4.5，这三族配深字。兜底那一份用的是固定原语而不是
+ * --xh-fg-default：实心底本身是原语色、不随主题翻，配色若跟着主题翻，暗色下就会变成
+ * 白字压在浅黄底上（实测对比度 2.70）。
  *
  * brand 是例外：那一族的色相归使用者，所以它的底与前景走 --xh-bg-brand / --xh-fg-on-brand
  * 这两个语义令牌。缺省主题下它们就解析成 brand-600 与 neutral-0，与其余五族同值；
  * 改写过品牌色的使用者只改这两个令牌，实心底与它上面的字就一起跟着走。
+ * 底与前景既然随主题翻，brand 的 shift 也必须随主题翻——现推那一档自动跟着底色走，
+ * 文件末尾那条深色覆盖是给兜底那一档用的。
  */
 @layer xihan.components {
   [data-tone] {
@@ -29,9 +35,6 @@
        而不是让 --xh-_tone 悬空——悬空会让下面每条 color-mix 变成计算期无效，
        用它的声明会整条失效，且 var() 兜底也救不回来（槽位是「已声明但无效」）。 */
     --xh-_tone: var(--xh-color-neutral-600);
-    /* 装饰性强调（色条、图标这类）用 500 档：600 是给实心底与文字用的强调档，
-       压在细长的色条上偏重。alert 与 toast 原本就用 500，接语气层不该改变它们的观感 */
-    --xh-_tone-soft: var(--xh-color-neutral-500);
     --xh-_tone-on: var(--xh-color-neutral-0);
     --xh-_tone-shift: var(--xh-color-neutral-950);
 
@@ -45,13 +48,18 @@
     /* 控件的可操作区边界要 3:1，兑了底色的 --xh-_tone-border 六族全在 1.44–2.18，够不着。
        这一支直接取主色本体；两族在各自的底上仍不够，在下面按主题单独兜 */
     --xh-_tone-border-control: var(--xh-_tone);
-    /* 在普通背景上表达该语气的文字色：往前景色兑，浅色态变深、深色态变浅 */
-    --xh-_tone-fg: color-mix(in oklab, var(--xh-_tone) 72%, var(--xh-fg-default));
+    /* 装饰性强调（色条、指示条、锚点高亮这类）是非文字图形，同样要 3:1，
+       要求与可操作区边界一模一样，就直接跟着那一支走，连它按主题兜的两族一并继承。
+       要读得清的状态文字不在此列，那些走 --xh-_tone-fg */
+    --xh-_tone-soft: var(--xh-_tone-border-control);
+    /* 在普通背景上表达该语气的文字色：往前景色兑，浅色态变深、深色态变浅。
+       兑到 60% 是实测出来的：这一档要同时压得住淡底的静态/悬停/按下三态、面与抬起的面
+       共五种底，72% 时六族里有三族够不到 4.5（最低 3.66），60% 全部达标且留有余量 */
+    --xh-_tone-fg: color-mix(in oklab, var(--xh-_tone) 60%, var(--xh-fg-default));
   }
 
   [data-tone='brand'] {
     --xh-_tone: var(--xh-bg-brand);
-    --xh-_tone-soft: var(--xh-color-brand-500);
     --xh-_tone-on: var(--xh-fg-on-brand);
     --xh-_tone-shift: var(--xh-color-neutral-950);
   }
@@ -64,28 +72,24 @@
 
   [data-tone='danger'] {
     --xh-_tone: var(--xh-color-danger-600);
-    --xh-_tone-soft: var(--xh-color-danger-500);
     --xh-_tone-on: var(--xh-color-neutral-0);
     --xh-_tone-shift: var(--xh-color-neutral-950);
   }
 
   [data-tone='success'] {
     --xh-_tone: var(--xh-color-success-600);
-    --xh-_tone-soft: var(--xh-color-success-500);
     --xh-_tone-on: var(--xh-color-neutral-950);
     --xh-_tone-shift: var(--xh-color-neutral-0);
   }
 
   [data-tone='warning'] {
     --xh-_tone: var(--xh-color-warning-600);
-    --xh-_tone-soft: var(--xh-color-warning-500);
     --xh-_tone-on: var(--xh-color-neutral-950);
     --xh-_tone-shift: var(--xh-color-neutral-0);
   }
 
   [data-tone='info'] {
     --xh-_tone: var(--xh-color-info-600);
-    --xh-_tone-soft: var(--xh-color-info-500);
     --xh-_tone-on: var(--xh-color-neutral-950);
     --xh-_tone-shift: var(--xh-color-neutral-0);
   }
@@ -109,4 +113,30 @@
   :is([data-theme='dark'] *, [data-theme='dark'])[data-tone='neutral'] {
     --xh-_tone-border-control: var(--xh-color-neutral-550);
   }
+
+  /* 把语气色转成线性 sRGB 分量、按 WCAG 的权重算出相对亮度：低于 0.179 前景取白、
+     高于取黑，挪动方向取前景的反面。三个通道写同一个式子，算出来的是纯白或纯黑；
+     alpha 显式写 1，不然会连语气色的透明度一起继承过来。
+     探针按这里实际用到的整个形态测，只测得起 color(from …) 的引擎不会落进半截支持。
+     上面各族写死的那一份是兜底：引擎不认这条语法时整块丢弃，退回那一份 */
+  @supports (color: color(from red srgb-linear clamp(0, (0.179 - (0.2126 * r + 0.7152 * g + 0.0722 * b)) * infinity, 1) 0 0 / 1)) {
+    [data-tone] {
+      --xh-_tone-on: color(from var(--xh-_tone) srgb-linear
+        clamp(0, (0.179 - (0.2126 * r + 0.7152 * g + 0.0722 * b)) * infinity, 1)
+        clamp(0, (0.179 - (0.2126 * r + 0.7152 * g + 0.0722 * b)) * infinity, 1)
+        clamp(0, (0.179 - (0.2126 * r + 0.7152 * g + 0.0722 * b)) * infinity, 1) / 1);
+      --xh-_tone-shift: color(from var(--xh-_tone) srgb-linear
+        clamp(0, ((0.2126 * r + 0.7152 * g + 0.0722 * b) - 0.179) * infinity, 1)
+        clamp(0, ((0.2126 * r + 0.7152 * g + 0.0722 * b) - 0.179) * infinity, 1)
+        clamp(0, ((0.2126 * r + 0.7152 * g + 0.0722 * b) - 0.179) * infinity, 1) / 1);
+    }
+  }
+
+  /* brand 的底与前景走语义令牌、随主题翻，所以它的 shift 也必须跟着翻，
+     否则深色下前景是深字而 shift 仍往深处挪，悬停与按下反而压低对比度
+     （实测 5.29 → 4.25 → 3.49，而不写 tone 的品牌链是 5.29 → 7.33 → 10.85）。
+     其余五族的底是固定原语、不随主题翻，shift 也就不必翻 */
+  :is([data-theme='dark'] *, [data-theme='dark'])[data-tone='brand'] {
+    --xh-_tone-shift: var(--xh-color-neutral-0);
+  }
 }

package/css/tooltip.css

@@ -69,7 +69,7 @@
        箭头是它的后代，语气槽一并继承 */
     --xh-_tooltip-py: var(--xh-space-1);
     --xh-_tooltip-px: var(--xh-space-2);
-    --xh-_tooltip-font-size: var(--xh-text-secondary-size);
+    --xh-_tooltip-font-size: var(--xh-control-caption-md);
 
     /* 与 positioner 相反：浮层本体要能接指针，指针停在提示上就不该收起
        （长文案需要停留细看）。positioner 仍是 none，空白区域照样点得穿。 */
@@ -127,4 +127,10 @@
 
     background: var(--xh-tooltip-bg, var(--xh-_tone, var(--xh-fg-default)));
   }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  [data-scope='tooltip'][data-part='trigger'][hidden] {
+    display: none;
+  }
 }

package/css/tour.css

@@ -87,6 +87,12 @@
     color: var(--xh-tour-fg, var(--xh-fg-default));
   }
 
+  /* 浮层被搬到 portal 落点，继承不到 root 上的槽：这把尺在被搬走的那一侧再声明一次，
+     关闭钮与条目里作者塞的图标才和皮肤画的兜底字形一样大 */
+  [data-scope='tour'][data-part='content'] {
+    --xh-icon-size: var(--xh-tour-icon-size, var(--xh-glyph-size-text));
+  }
+
   /* 遮罩：整页压暗，把注意力逼到高亮框那一块上 */
   [data-scope='tour'][data-part='backdrop'] {
     position: fixed;
@@ -165,7 +171,7 @@
     display: flex;
     align-items: center;
     justify-content: center;
-    padding: var(--xh-space-4);
+    padding: var(--xh-tour-positioner-padding, var(--xh-space-4));
   }
 
   /* 必须排在 data-position='center' 之后：两条选择器的特指度相同（都是三个属性），
@@ -246,9 +252,9 @@
     align-items: center;
     justify-content: center;
     block-size: var(--xh-control-h-sm);
-    padding-inline: var(--xh-control-px-md);
+    padding-inline: var(--xh-tour-skip-trigger-px, var(--xh-control-px-md));
     border: var(--xh-stroke-thin) solid transparent;
-    border-radius: var(--xh-shape-control);
+    border-radius: var(--xh-tour-action-radius, var(--xh-shape-control));
     font-size: var(--xh-text-secondary-size);
     cursor: pointer;
   }