@xihan-ui/styles 1.0.0 → 2.0.0

package/css/toolbar.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.
+ */
+
+/* 定义 toolbar 样式。 */
+
+/* 独立皮肤传递引入条目的动作控件配方，full bundle 递归去重。 */
+@import '../family/action-control.css';
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='toolbar'] {
@@ -7,19 +17,35 @@
   /* 一条控件带：条目之间留固定间距，分隔线再把它们切成语义上的几段。
      排布只能读 data-orientation——它与 aria-orientation 同源，但样式不该去读 ARIA */
   [data-scope='toolbar'][data-part='root'] {
-    /* 尺寸档只换这两个私有槽：条目之间的间距，与整条的内边距 */
-    --xh-_toolbar-gap: var(--xh-space-1);
+    /* 尺寸档同时约束工具条排布与默认条目。 */
+    --xh-_toolbar-gap: var(--xh-space-2);
     --xh-_toolbar-p: var(--xh-space-1);
+    --xh-_toolbar-item-h: var(--xh-control-h-md);
+    --xh-_toolbar-separator-size: calc(var(--xh-_toolbar-item-h) / 2);
+    --xh-icon-size: var(--xh-toolbar-icon-size, var(--xh-glyph-size-md));
+
+    /* 缺省 ghost：工具条只组织控件，不额外画外框；条目按画布承载走 hover 100 → pressed 200。 */
+    --xh-_toolbar-root-p: 0;
+    --xh-_toolbar-root-border-width: 0;
+    --xh-_toolbar-root-border: transparent;
+    --xh-_toolbar-root-bg: transparent;
+    --xh-_toolbar-root-bg-disabled: transparent;
 
+    /* 一行排不下就折行：条目宽度由各自的控件决定，硬撑一行会把整条顶出容器 */
     display: flex;
+    flex-wrap: wrap;
     align-items: center;
     gap: var(--xh-toolbar-gap, var(--xh-_toolbar-gap));
-    padding-block: var(--xh-toolbar-py, var(--xh-_toolbar-p));
-    padding-inline: var(--xh-toolbar-px, var(--xh-_toolbar-p));
-    border: var(--xh-stroke-thin) solid var(--xh-toolbar-border, var(--xh-border-default));
+    padding-block: var(--xh-toolbar-py, var(--xh-_toolbar-root-p));
+    padding-inline: var(--xh-toolbar-px, var(--xh-_toolbar-root-p));
+    border: var(--xh-_toolbar-root-border-width) solid var(--xh-toolbar-border, var(--xh-_toolbar-root-border));
     border-radius: var(--xh-toolbar-radius, var(--xh-shape-surface));
-    background: var(--xh-toolbar-bg, var(--xh-bg-surface));
+    background: var(--xh-toolbar-bg, var(--xh-_toolbar-root-bg));
     color: var(--xh-toolbar-fg, var(--xh-fg-default));
+    /* 整条置灰与恢复是一次状态切换，底色与字色淡着换，不硬切 */
+    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='toolbar'][data-part='root'][data-orientation='horizontal'] {
@@ -30,6 +56,38 @@
   [data-scope='toolbar'][data-part='root'][data-orientation='vertical'] {
     flex-direction: column;
     align-items: stretch;
+    flex-wrap: nowrap;
+  }
+
+  /* —— 变体 —— */
+  [data-scope='toolbar'][data-part='root'][data-variant='ghost'] {
+    --xh-_toolbar-root-p: 0;
+    --xh-_toolbar-root-border-width: 0;
+    --xh-_toolbar-root-border: transparent;
+    --xh-_toolbar-root-bg: transparent;
+    --xh-_toolbar-root-bg-disabled: transparent;
+  }
+
+  /* 淡底档：带内距、换成 subtle 底，描边让位给底色但留住 1px 边位（与 outline 几何一致），无影；
+     淡底承载面向条目下发 hover 200 → pressed 300（§7.2） */
+  [data-scope='toolbar'][data-part='root'][data-variant='subtle'] {
+    --xh-_toolbar-root-p: var(--xh-_toolbar-p);
+    --xh-_toolbar-root-border-width: var(--xh-stroke-thin);
+    --xh-_toolbar-root-bg: var(--xh-bg-subtle);
+    --xh-action-host-bg-hover: var(--xh-bg-subtle-hover);
+    --xh-action-host-bg-pressed: var(--xh-bg-subtle-active);
+  }
+
+  /* 附着式工具面：一张静态内容面，--xh-border-default 描边 + surface 底 + 无影（§5.3 边界只由描边承担）。 */
+  [data-scope='toolbar'][data-part='root'][data-variant='outline'] {
+    --xh-_toolbar-root-p: var(--xh-_toolbar-p);
+    --xh-_toolbar-root-border-width: var(--xh-stroke-thin);
+    --xh-_toolbar-root-border: var(--xh-border-default);
+    --xh-_toolbar-root-bg: var(--xh-bg-surface);
+    --xh-_toolbar-root-bg-disabled: var(--xh-bg-muted);
+
+    border-radius: var(--xh-toolbar-radius, var(--xh-shape-surface));
+    box-shadow: var(--xh-toolbar-shadow, none);
   }
 
   /* —— 尺寸 —— */
@@ -38,11 +96,15 @@
   [data-scope='toolbar'][data-part='root'][data-size='sm'] {
     --xh-_toolbar-gap: var(--xh-space-0_5);
     --xh-_toolbar-p: var(--xh-space-0_5);
+    --xh-_toolbar-item-h: var(--xh-control-h-sm);
+    --xh-icon-size: var(--xh-toolbar-icon-size, var(--xh-glyph-size-sm));
   }
 
   [data-scope='toolbar'][data-part='root'][data-size='lg'] {
-    --xh-_toolbar-gap: var(--xh-space-2);
+    --xh-_toolbar-gap: var(--xh-space-3);
     --xh-_toolbar-p: var(--xh-space-2);
+    --xh-_toolbar-item-h: var(--xh-control-h-lg);
+    --xh-icon-size: var(--xh-toolbar-icon-size, var(--xh-glyph-size-lg));
   }
 
   /* root 会在焦点进条前短暂拿到 tabindex=0，但它的 onFocus 立刻把焦点转投给条目，
@@ -52,9 +114,8 @@
   }
 
   [data-scope='toolbar'][data-part='root'][data-disabled] {
-    background: var(--xh-toolbar-bg-disabled, var(--xh-bg-muted));
+    background: var(--xh-toolbar-bg-disabled, var(--xh-_toolbar-root-bg-disabled));
     color: var(--xh-fg-disabled);
-    cursor: not-allowed;
   }
 
   /* 给了 display 的角色节点必须补这条：display 声明会盖掉 UA 的 [hidden]{display:none}，
@@ -63,57 +124,144 @@
     display: none;
   }
 
-  /* 分组把一串相关控件收得更紧：组内间距比条上的总间距小，
-     "这几个是一伙的"才看得出来 */
+  /* 分组只负责把相关操作连成一条，表面与交互状态由每个分段自己绘制。 */
   [data-scope='toolbar'][data-part='group'] {
-    display: flex;
-    align-items: center;
-    gap: var(--xh-toolbar-group-gap, var(--xh-space-0_5));
+    display: inline-flex;
+    flex-wrap: nowrap;
+    align-items: stretch;
+    gap: var(--xh-toolbar-group-gap, var(--xh-space-0));
+    background: transparent;
   }
 
   [data-scope='toolbar'][data-part='group'][data-orientation='vertical'] {
     flex-direction: column;
     align-items: stretch;
+    flex-wrap: nowrap;
   }
 
   [data-scope='toolbar'][data-part='group'][hidden] {
     display: none;
   }
 
-  /* 条目是作者自己的控件（按钮、切换钮、下拉触发器），观感归它自己的皮肤。
-     这里只补两件与导航直接相关的事：焦点环与禁用光标。
-     刻意不给 display——给了会把条目自身皮肤里的排布盖掉，也就不必补 [hidden] 那条 */
-  [data-scope='toolbar'][data-part='item']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
+  /* 默认条目是一枚无描边工具按钮：盒型、三档几何、悬停 / 按下 / 禁用面与按压缩放由 Action Control 的
+     text 档给（ghost 形态：ghost 根按画布承载 hover 100 → pressed 200，subtle 根与分组由 host 槽下发
+     200 → 300，§7.2）；这里只把使用者槽映射到桥接槽（-gap / -h / -px / -radius / -bg / -bg-hover /
+     -bg-active / -bg-disabled / -fg / -font-size 保留为第一参数）。作者仍可用类名或内联样式完整覆盖。 */
+  [data-scope='toolbar'][data-part='item'] {
+    --xh-action-gap: var(--xh-toolbar-item-gap, var(--xh-control-gap-sm));
+    --xh-action-visual-size: var(--xh-toolbar-item-h, var(--xh-_action-profile-visual-size));
+    --xh-action-padding-inline: var(--xh-toolbar-item-px, var(--xh-_action-profile-padding-inline));
+    --xh-action-radius: var(--xh-toolbar-item-radius, var(--xh-_action-profile-radius));
+    --xh-action-bg-rest: var(--xh-toolbar-item-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-toolbar-item-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-toolbar-item-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-bg-disabled: var(--xh-toolbar-item-bg-disabled, var(--xh-_action-variant-bg-disabled));
+    --xh-action-fg-rest: var(--xh-toolbar-item-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-toolbar-item-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-toolbar-item-fg, var(--xh-_action-variant-fg-pressed));
+    --xh-action-font-size: var(--xh-toolbar-item-font-size, var(--xh-_action-profile-font-size));
+
+    font-weight: var(--xh-toolbar-item-font-weight, var(--xh-text-label-weight));
+    touch-action: manipulation;
   }
 
-  /* 集合条目一律 aria-disabled 而非原生 disabled（禁用项仍要能当方向键的起点），
-     所以这里读 data-disabled，写 :disabled 永远不命中 */
-  [data-scope='toolbar'][data-part='item'][data-disabled] {
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
+  /* 无滑块开关的按下态（§7.3）：品牌淡底 + 淡底前景，hover / 按下沿 12% → 20% → 28% 三档走；
+     三态都经桥接槽交给家族画，禁用面仍由家族按 data-disabled 给 */
+  [data-scope='toolbar'][data-part='item'][aria-pressed='true'] {
+    --xh-action-bg-rest: var(--xh-toolbar-item-bg-pressed, var(--xh-bg-brand-subtle));
+    --xh-action-bg-hover: var(--xh-toolbar-item-bg-pressed-hover, var(--xh-bg-brand-subtle-hover));
+    --xh-action-bg-pressed: var(--xh-toolbar-item-bg-pressed-active, var(--xh-bg-brand-subtle-active));
+    --xh-action-fg-rest: var(--xh-toolbar-item-fg-pressed, var(--xh-fg-on-brand-subtle));
+    --xh-action-fg-hover: var(--xh-toolbar-item-fg-pressed, var(--xh-fg-on-brand-subtle));
+    --xh-action-fg-pressed: var(--xh-toolbar-item-fg-pressed, var(--xh-fg-on-brand-subtle));
+  }
+
+  [data-scope='toolbar'][data-part='item'][hidden] {
+    display: none;
   }
 
-  /* 分隔线画的是它自己的朝向：横排工具条里它是竖线，连接层给的就是 vertical。
-     粗的那一维写死描边宽度，长的那一维交给 align-self 拉伸，
-     沿长边再内缩一点，线才不会顶到工具条的上下边 */
+  /* 组内分段使用同一块中性操作面（淡底承载：hover 200 → pressed 300 由 host 槽下发）；
+     中间段保持直角，只给整组两端补回控件圆角。按下态 / 禁用面与散落条目同一套规则 */
+  [data-scope='toolbar'][data-part='group'] > [data-scope='toolbar'][data-part='item'] {
+    --xh-action-host-bg-hover: var(--xh-bg-subtle-hover);
+    --xh-action-host-bg-pressed: var(--xh-bg-subtle-active);
+    --xh-action-radius: 0;
+    --xh-action-bg-disabled: var(--xh-toolbar-item-bg-disabled, var(--xh-bg-subtle));
+
+    position: relative;
+  }
+
+  /* 组内未选中的段才铺中性面：选中段的品牌淡底由上面 aria-pressed 那条给，这条比它更特定，不守卫会把它盖掉 */
+  [data-scope='toolbar'][data-part='group'] > [data-scope='toolbar'][data-part='item']:not([aria-pressed='true']) {
+    --xh-action-bg-rest: var(--xh-toolbar-item-bg, var(--xh-bg-subtle));
+  }
+
+  [data-scope='toolbar'][data-part='group'][data-orientation='horizontal']
+    > [data-scope='toolbar'][data-part='item']:first-of-type {
+    border-start-start-radius: var(--xh-toolbar-item-radius, var(--xh-shape-control));
+    border-end-start-radius: var(--xh-toolbar-item-radius, var(--xh-shape-control));
+  }
+
+  [data-scope='toolbar'][data-part='group'][data-orientation='horizontal']
+    > [data-scope='toolbar'][data-part='item']:last-of-type {
+    border-start-end-radius: var(--xh-toolbar-item-radius, var(--xh-shape-control));
+    border-end-end-radius: var(--xh-toolbar-item-radius, var(--xh-shape-control));
+  }
+
+  [data-scope='toolbar'][data-part='group'][data-orientation='vertical']
+    > [data-scope='toolbar'][data-part='item']:first-of-type {
+    border-start-start-radius: var(--xh-toolbar-item-radius, var(--xh-shape-control));
+    border-start-end-radius: var(--xh-toolbar-item-radius, var(--xh-shape-control));
+  }
+
+  [data-scope='toolbar'][data-part='group'][data-orientation='vertical']
+    > [data-scope='toolbar'][data-part='item']:last-of-type {
+    border-end-start-radius: var(--xh-toolbar-item-radius, var(--xh-shape-control));
+    border-end-end-radius: var(--xh-toolbar-item-radius, var(--xh-shape-control));
+  }
+
+  /* 分隔线取控件高度的一半；横排工具条里画竖线，竖排工具条里画横线。 */
   [data-scope='toolbar'][data-part='separator'] {
     flex: none;
-    align-self: stretch;
+    align-self: center;
     border-radius: var(--xh-toolbar-separator-radius, var(--xh-shape-pill));
     background: var(--xh-toolbar-separator-color, var(--xh-border-default));
   }
 
   [data-scope='toolbar'][data-part='separator'][data-orientation='vertical'] {
     inline-size: var(--xh-toolbar-separator-thickness, var(--xh-stroke-thin));
-    margin-block: var(--xh-toolbar-separator-inset, var(--xh-space-1));
-    margin-inline: var(--xh-toolbar-separator-gap, var(--xh-space-1));
+    block-size: var(--xh-_toolbar-separator-size);
+    margin-block: var(--xh-toolbar-separator-inset, var(--xh-space-0));
+    margin-inline: var(--xh-toolbar-separator-gap, var(--xh-space-0));
   }
 
   [data-scope='toolbar'][data-part='separator'][data-orientation='horizontal'] {
     block-size: var(--xh-toolbar-separator-thickness, var(--xh-stroke-thin));
-    margin-block: var(--xh-toolbar-separator-gap, var(--xh-space-1));
-    margin-inline: var(--xh-toolbar-separator-inset, var(--xh-space-1));
+    inline-size: var(--xh-_toolbar-separator-size);
+    margin-block: var(--xh-toolbar-separator-gap, var(--xh-space-0));
+    margin-inline: var(--xh-toolbar-separator-inset, var(--xh-space-0));
+  }
+
+  /* 组内分隔线覆盖在相邻分段的接缝上，不占额外宽度；半高弱线保留整体连续感。 */
+  [data-scope='toolbar'][data-part='group'] > [data-scope='toolbar'][data-part='separator'] {
+    background: var(--xh-toolbar-separator-color, var(--xh-fg-default));
+    opacity: var(--xh-toolbar-separator-opacity, var(--xh-control-separator-opacity));
+    pointer-events: none;
+  }
+
+  [data-scope='toolbar'][data-part='group'] > [data-scope='toolbar'][data-part='separator'][data-orientation='vertical'] {
+    margin-inline-start: calc(-1 * var(--xh-toolbar-separator-thickness, var(--xh-stroke-thin)));
+  }
+
+  [data-scope='toolbar'][data-part='group'] > [data-scope='toolbar'][data-part='separator'][data-orientation='horizontal'] {
+    margin-block-start: calc(-1 * var(--xh-toolbar-separator-thickness, var(--xh-stroke-thin)));
+  }
+
+  @media (forced-colors: active) {
+    /* 分段之间那条线画的是一块纯底色，这一档里底色被统一换成 Canvas，线整条消失，
+       几段控件就连成了一长串。换成前景色画回来 */
+    [data-scope='toolbar'][data-part='separator'] {
+      background: CanvasText;
+    }
   }
 }

package/css/tooltip.css

@@ -1,30 +1,12 @@
-@layer xihan.motion {
-  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
-     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
-  @keyframes xh-pop-in {
-    from {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
 
-    to {
-      opacity: 1;
-      scale: 1;
-    }
-  }
+/* 定义 tooltip 样式。 */
 
-  @keyframes xh-pop-out {
-    from {
-      opacity: 1;
-      scale: 1;
-    }
-
-    to {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
-  }
-}
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
 
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
@@ -44,17 +26,23 @@
     cursor: inherit;
   }
 
-  [data-scope='tooltip'][data-part='trigger']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
+  /* 这里的 data-disabled 关掉的是提示，不是宿主控件：光标仍旧交给宿主 */
+  [data-scope='tooltip'][data-part='trigger'][data-disabled] {
+    cursor: inherit;
   }
 
   /* 坐标由定位引擎写在行内 style 上，这里只兜底 SSR 首帧 */
   [data-scope='tooltip'][data-part='positioner'] {
+    /* 先截断祖先浮层的方向，再按本次实际 placement 只启用一侧。 */
+    --xh-_overlay-enter-up: 0;
+    --xh-_overlay-enter-down: 0;
+    --xh-_overlay-enter-left: 0;
+    --xh-_overlay-enter-right: 0;
+
     position: fixed;
     inset-block-start: 0;
     inset-inline-start: 0;
-    z-index: var(--xh-tooltip-layer, var(--xh-layer-tooltip));
+    z-index: var(--xh-tooltip-layer, var(--xh-_layer, var(--xh-layer-tooltip)));
     /* 浮层不承载交互：指针必须能穿过去点到底下的东西 */
     pointer-events: none;
   }
@@ -64,18 +52,44 @@
     visibility: hidden;
   }
 
+  /* 进退位移按落定的那一侧给。placement 与 translate 都是物理方向，不随书写方向翻。 */
+  [data-scope='tooltip'][data-part='positioner'][data-placement^='top'] {
+    --xh-_overlay-enter-down: 1;
+  }
+
+  [data-scope='tooltip'][data-part='positioner'][data-placement^='bottom'] {
+    --xh-_overlay-enter-up: 1;
+  }
+
+  [data-scope='tooltip'][data-part='positioner'][data-placement^='left'] {
+    --xh-_overlay-enter-right: 1;
+  }
+
+  [data-scope='tooltip'][data-part='positioner'][data-placement^='right'] {
+    --xh-_overlay-enter-left: 1;
+  }
+
   [data-scope='tooltip'][data-part='content'] {
     /* 尺寸档只换这三个私有槽。tooltip 没有 root 部件，两轴都落在浮层树最外层的 content 上，
        箭头是它的后代，语气槽一并继承 */
     --xh-_tooltip-py: var(--xh-space-1);
     --xh-_tooltip-px: var(--xh-space-2);
     --xh-_tooltip-font-size: var(--xh-control-caption-md);
+    /* Tooltip 保留反白身份（真源 §8.4 登记的反白 compact frosted）：短提示要与可交互的普通主题浮层一眼分开。
+       94% 是六种 tone 在纯黑/纯白最坏底色上仍托住 4.5:1 正文的首个安全档。
+       边不取 --xh-material-frosted-border：那是深色 14% 的透明边，压在反白深底上看不见，
+       §8.1 要求的 1px 可见边界由 on 色 20% 拼色承担；§8.1 禁玻璃高光，顶光缺省不画 */
+    --xh-_tooltip-solid: var(--xh-_tone, var(--xh-fg-default));
+    --xh-_tooltip-on: var(--xh-_tone-on, var(--xh-bg-surface));
+    --xh-_tooltip-border: color-mix(in oklab, var(--xh-_tooltip-on) 20%, transparent);
 
     /* 与 positioner 相反：浮层本体要能接指针，指针停在提示上就不该收起
        （长文案需要停留细看）。positioner 仍是 none，空白区域照样点得穿。 */
     /* 显式声明 display 是为了盖掉 UA 的 [hidden]{display:none}：收起那一帧 content 仍带 hidden，
        盒子得先在,退场动画才播得出来。真正的收起由宿主在退场结束后落成内联 display */
     display: block;
+    position: relative;
+    isolation: isolate;
     pointer-events: auto;
     max-inline-size: var(--xh-tooltip-max-w, var(--xh-overlay-max-w));
     padding-block: var(--xh-tooltip-py, var(--xh-_tooltip-py));
@@ -83,22 +97,47 @@
     /* 这里刻意用 control 而不是浮层那档 surface：提示气泡通常只有一行字、高度接近控件，
        8px 圆角在这个尺寸上占比过大，看着会发胖。档位定义里为此单列了一条 */
     border-radius: var(--xh-tooltip-radius, var(--xh-shape-control));
-    /* 实心底与其上的文字色随语气走。没写 data-tone 时两个槽都没被声明，退回原来的取值 */
-    background: var(--xh-tooltip-bg, var(--xh-_tone, var(--xh-fg-default)));
-    color: var(--xh-tooltip-fg, var(--xh-_tone-on, var(--xh-bg-surface)));
+    border: var(--xh-stroke-thin) solid var(--xh-tooltip-border, var(--xh-_tooltip-border));
+    background: transparent;
+    color: var(--xh-tooltip-fg, var(--xh-_tooltip-on));
     font-size: var(--xh-tooltip-font-size, var(--xh-_tooltip-font-size));
     line-height: var(--xh-leading-normal);
-    box-shadow: var(--xh-tooltip-shadow, var(--xh-elevation-floating));
+    overflow-wrap: anywhere;
+    text-wrap: pretty;
+    --xh-_tooltip-elevation-shadow: var(--xh-tooltip-shadow, var(--xh-material-frosted-compact-shadow));
+
+    /* 顶光槽缺省透明（§8.1 不用顶部高光），使用者要加自行灌色 */
+    box-shadow:
+      inset 0 var(--xh-stroke-thin) 0 var(--xh-tooltip-highlight, transparent),
+      var(--xh-_tooltip-elevation-shadow);
+    -webkit-backdrop-filter: var(--xh-tooltip-backdrop, var(--xh-material-frosted-compact-backdrop));
+    backdrop-filter: var(--xh-tooltip-backdrop, var(--xh-material-frosted-compact-backdrop));
   }
 
+  /* 光学层单独承载 tint 与透明度；backdrop-filter 只采样元素背后，不处理正文。 */
+  [data-scope='tooltip'][data-part='content']::before {
+    content: '';
+    position: absolute;
+    z-index: -1;
+    inset: 0;
+    border-radius: inherit;
+    background: var(--xh-tooltip-bg, var(--xh-_tooltip-solid));
+    opacity: var(--xh-material-frosted-compact-alpha);
+    pointer-events: none;
+  }
+
+  /* 入场走 enter 档（§9.5：锚定列表族的 tooltip 入场 --xh-motion-duration-enter），退场仍是 exit */
   [data-scope='tooltip'][data-part='content'][data-state='open'] {
-    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    animation: xh-overlay-slide-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+    /* 只在开着的这一档挂：合成层随 data-state 一起收走，收起后不再占着 */
+    will-change: opacity, translate;
   }
 
   /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
      免得动画结束到真收起之间闪一下原样 */
   [data-scope='tooltip'][data-part='content'][data-state='closed'] {
-    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+    will-change: opacity, translate;
+    animation: xh-overlay-slide-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   /* —— 尺寸 —— */
@@ -125,7 +164,31 @@
     --xh-_overlay-arrow-x: var(--xh-_tooltip-arrow-x);
     --xh-_overlay-arrow-y: var(--xh-_tooltip-arrow-y);
 
-    background: var(--xh-tooltip-bg, var(--xh-_tone, var(--xh-fg-default)));
+    background: var(--xh-tooltip-bg, var(--xh-_tooltip-solid));
+    border: var(--xh-stroke-thin) solid var(--xh-tooltip-border, var(--xh-_tooltip-border));
+    opacity: var(--xh-material-frosted-compact-alpha);
+  }
+
+  /* 高对比仍保持反白语义：compact 配方已把 tint / blur / shadow 换成实体档，此处只加强同色边界。 */
+  :is([data-contrast='more'] *, [data-contrast='more'])[data-scope='tooltip'][data-part='content'] {
+    --xh-_tooltip-border: var(--xh-_tooltip-on);
+  }
+
+  @media (forced-colors: active) {
+    [data-scope='tooltip'][data-part='content'],
+    [data-scope='tooltip'][data-part='arrow'] {
+      border-color: CanvasText;
+      background: Canvas;
+      color: CanvasText;
+      box-shadow: none;
+      -webkit-backdrop-filter: none;
+      backdrop-filter: none;
+    }
+
+    [data-scope='tooltip'][data-part='content']::before {
+      background: Canvas;
+      opacity: 1;
+    }
   }
 
   /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
@@ -133,4 +196,12 @@
   [data-scope='tooltip'][data-part='trigger'][hidden] {
     display: none;
   }
+
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    [data-scope='tooltip'][data-part='positioner'] {
+      display: none;
+    }
+  }
 }