@xihan-ui/styles 1.0.0 → 2.0.0

package/css/menubar.css

@@ -1,3 +1,14 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 menubar 样式。 */
+
+/* 共享关键帧由 family/motion.css 提供，条目走 Collection Item 家族；本皮肤 @import 它们，单独引入仍成立。 */
+@import '../family/collection-item.css';
+@import '../family/motion.css';
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='menubar'] {
@@ -6,23 +17,17 @@
 
   /* 一排 trigger。主轴跟着 data-orientation 走：菜单栏本身可以横排也可以竖排 */
   [data-scope='menubar'][data-part='root'] {
-    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
-    --xh-icon-size: var(--xh-menubar-icon-size, var(--xh-glyph-size-text));
-
+    /* 一行排不下就折行：菜单名宽度由文字决定，硬撑一行会把整条顶出容器，
+       末尾几个菜单既看不见也点不到 */
     display: flex;
+    flex-wrap: wrap;
     align-items: center;
-    gap: var(--xh-menubar-root-gap, var(--xh-space-1));
-    padding-block: var(--xh-menubar-root-py, var(--xh-space-1));
-    padding-inline: var(--xh-menubar-root-px, var(--xh-space-1));
-    border-radius: var(--xh-menubar-root-radius, var(--xh-shape-control));
-    background: var(--xh-menubar-root-bg, transparent);
-    color: var(--xh-menubar-root-fg, var(--xh-fg-default));
-  }
-
-  /* 浮层被搬到 portal 落点，继承不到 root 上的槽：这把尺在被搬走的那一侧再声明一次，
-     关闭钮与条目里作者塞的图标才和皮肤画的兜底字形一样大 */
-  [data-scope='menubar'][data-part='content'] {
-    --xh-icon-size: var(--xh-menubar-icon-size, var(--xh-glyph-size-text));
+    gap: var(--xh-menubar-gap, var(--xh-space-1));
+    padding-block: var(--xh-menubar-py, var(--xh-space-1));
+    padding-inline: var(--xh-menubar-px, var(--xh-space-1));
+    border-radius: var(--xh-menubar-radius, var(--xh-shape-control));
+    background: var(--xh-menubar-bg, transparent);
+    color: var(--xh-menubar-fg, var(--xh-fg-default));
   }
 
   [data-scope='menubar'][data-part='root'][hidden] {
@@ -32,6 +37,7 @@
   [data-scope='menubar'][data-part='root'][data-orientation='vertical'] {
     flex-direction: column;
     align-items: stretch;
+    flex-wrap: nowrap;
   }
 
   /* root 只是 roving tabindex 的兜底落点，焦点转投给 trigger 之后就不再停留，不画环 */
@@ -43,63 +49,56 @@
     color: var(--xh-fg-disabled);
   }
 
+  /* 入口归 Collection Item 展开路径 / 打开中（nav 语境）：几何、字号与面全经家族桥接槽。静息字色取 default
+     （菜单名不是次要文字，不取 nav 缺省的 muted），悬停走白底承载 hover 100，展开着的那一张由连接层投影
+     data-in-path，家族给与悬停同档的中性面——打开中不是选中，不用品牌色、不接语气、不加粗（§7.3）；
+     按下 pressed 200 只换面不缩放（§9.2）；禁用走 aria-disabled，家族给禁用字色与 not-allowed。
+     本条 (0,2,0) 压过家族基础块 (0,1,0)，不能再写 background / color / cursor */
   [data-scope='menubar'][data-part='trigger'] {
+    --xh-collection-block-padding: var(--xh-menubar-trigger-py, var(--xh-_menubar-trigger-py));
+    --xh-collection-inline-padding: var(--xh-menubar-trigger-px, var(--xh-_menubar-trigger-px));
+    --xh-collection-radius: var(--xh-menubar-trigger-radius, var(--xh-shape-control));
+    --xh-collection-font-size: var(--xh-menubar-trigger-font-size, var(--xh-_menubar-font-size));
+    --xh-collection-fg-rest: var(--xh-menubar-trigger-fg, var(--xh-fg-default));
+    --xh-collection-bg-hover: var(--xh-menubar-trigger-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-open-path: var(--xh-menubar-trigger-bg-active, var(--xh-bg-subtle));
+    --xh-collection-bg-pressed: var(--xh-menubar-trigger-bg-pressed, var(--xh-bg-subtle-hover));
+
     display: inline-flex;
     flex: none;
     align-items: center;
     gap: var(--xh-menubar-trigger-gap, var(--xh-control-gap-sm));
-    padding-block: var(--xh-menubar-trigger-py, var(--xh-_menubar-trigger-py));
-    padding-inline: var(--xh-menubar-trigger-px, var(--xh-_menubar-trigger-px));
     border: none;
-    border-radius: var(--xh-menubar-trigger-radius, var(--xh-shape-control));
-    background: transparent;
-    color: inherit;
-    font: inherit;
-    font-size: var(--xh-menubar-trigger-font-size, var(--xh-_menubar-font-size));
+    /* 不再写 font: inherit：按钮的 UA 字体由 reset.css 抹平，这里再写一遍会把家族给的字号与字重一并盖掉。
+       行高压回 none：家族基础块给条目写了 leading-normal，入口的高度只由内缩定 */
     line-height: var(--xh-leading-none);
     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]):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 位（整条菜单栏唯一的那个），必须画得出焦点 */
-  [data-scope='menubar'][data-part='trigger']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
-  }
-
-  /* 禁用走 aria-disabled 而非原生 disabled：trigger 仍要可聚焦（它还得当方向键的起点），
-     所以只能靠 data-disabled 表达，写 :disabled 永远不命中 */
-  [data-scope='menubar'][data-part='trigger'][data-disabled] {
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
-  }
-
   /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
   [data-scope='menubar'][data-part='positioner'] {
     /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，content 继承它限高；
        引擎没算（尚未落位 / 无引擎）时不额外限高 */
     --xh-_menubar-available-h: 100vh;
+    /* 落定那一侧的可用宽度，同样由定位引擎经内联自定义属性写进来，行内轴据此夹取；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时退到视口宽 */
+    --xh-_menubar-available-w: 100vw;
+    /* WC 子菜单仍可能住在父 positioner 内；先截断父层方向，避免斜向继承。 */
+    --xh-_overlay-enter-up: 0;
+    --xh-_overlay-enter-down: 0;
+    --xh-_overlay-enter-left: 0;
+    --xh-_overlay-enter-right: 0;
+
+    /* 条目列表的自绘条浮在内容之上：轨道不上底色，实色轨道会在菜单右缘糊一条竖灰带 */
+    --xh-scrollbar-track-bg: transparent;
 
     position: fixed;
-    z-index: var(--xh-menubar-layer, var(--xh-layer-popover));
+    z-index: var(--xh-menubar-layer, var(--xh-_layer, var(--xh-layer-popover)));
     /* 空壳不吃指针，交互只发生在 content 上 */
     pointer-events: none;
   }
@@ -109,29 +108,45 @@
     visibility: hidden;
   }
 
+  /* 物理 placement 与定位引擎同口径，不随书写方向翻转。 */
+  [data-scope='menubar'][data-part='positioner'][data-placement^='top'] {
+    --xh-_overlay-enter-down: 1;
+  }
+
+  [data-scope='menubar'][data-part='positioner'][data-placement^='bottom'] {
+    --xh-_overlay-enter-up: 1;
+  }
+
+  [data-scope='menubar'][data-part='positioner'][data-placement^='left'] {
+    --xh-_overlay-enter-right: 1;
+  }
+
+  [data-scope='menubar'][data-part='positioner'][data-placement^='right'] {
+    --xh-_overlay-enter-left: 1;
+  }
+
   /* —— 尺寸 —— */
   /* 尺寸档只换这六个私有槽，换档不必给每个部件各写一条选择器。
      root 与 positioner 各起一头：trigger 从 root 继承，菜单里的条目从 positioner 继承——
      浮层搬去了 portal 落点，不再是 root 的后代。
      缺省档写在第一条：trigger 与条目的行内内缩都走 control-px 档（随密度轴）、纵向走 space 档，换档各挪一级 */
   [data-scope='menubar']:is([data-part='root'], [data-part='positioner']) {
+    /* 条目外的字形（分组标题、入口）按档取尺，缺省 md，随 data-size 换档；同样声明在 positioner 上，被搬走的
+       浮层才拿得到；条目里作者放的图标由家族随 data-xh-collection-size 下发（§6.5）。菜单栏自绘的状态字形（标记位的盒、
+       盒里兜底的勾、子菜单的展开 chevron）不读这支：它们是指示符，走 --xh-control-indicator-* 一族——标记位在
+       自己身上把 --xh-icon-size 改接到盒的尺，子菜单箭头走 --xh-menubar-submenu-indicator-size */
+    --xh-icon-size: var(--xh-menubar-icon-size, var(--xh-glyph-size-md));
+
     --xh-_menubar-trigger-py: var(--xh-space-1);
     --xh-_menubar-trigger-px: var(--xh-control-px-md);
     --xh-_menubar-item-py: var(--xh-list-option-py-md);
     --xh-_menubar-item-px: var(--xh-control-px-md);
     --xh-_menubar-item-gap: var(--xh-control-gap-md);
     --xh-_menubar-font-size: var(--xh-control-font-md);
-
-    /* 展开着的那张菜单的 trigger 走品牌淡底强档，随语气换色相；没写 data-tone 时退回品牌淡底。
-       悬停与键盘焦点恒中性灰轻档、不接语气槽——两档同色相的话哪张开着就认不出来了。
-       聚焦环不在其列，它恒是 --xh-ring-focus */
-    --xh-_menubar-active-bg: var(--xh-_tone-subtle, var(--xh-bg-brand-subtle));
-
-    /* 打开子菜单的触发条目走品牌淡底强档，随语气换色相；没写 data-tone 时退回品牌淡底 */
-    --xh-_menubar-item-active-bg: var(--xh-_tone-subtle, var(--xh-bg-brand-subtle));
   }
 
   [data-scope='menubar'][data-size='sm']:is([data-part='root'], [data-part='positioner']) {
+    --xh-icon-size: var(--xh-menubar-icon-size, var(--xh-glyph-size-sm));
     --xh-_menubar-trigger-py: var(--xh-space-0_5);
     --xh-_menubar-trigger-px: var(--xh-control-px-sm);
     --xh-_menubar-item-py: var(--xh-list-option-py-sm);
@@ -141,6 +156,7 @@
   }
 
   [data-scope='menubar'][data-size='lg']:is([data-part='root'], [data-part='positioner']) {
+    --xh-icon-size: var(--xh-menubar-icon-size, var(--xh-glyph-size-lg));
     --xh-_menubar-trigger-py: var(--xh-space-2);
     --xh-_menubar-trigger-px: var(--xh-control-px-lg);
     --xh-_menubar-item-py: var(--xh-list-option-py-lg);
@@ -150,26 +166,44 @@
   }
 
   [data-scope='menubar'][data-part='content'] {
+    position: relative;
     display: flex;
     flex-direction: column;
     gap: var(--xh-menubar-content-gap, var(--xh-list-option-gap));
     min-inline-size: var(--xh-menubar-min-w, var(--xh-overlay-menu-min-w));
-    max-inline-size: var(--xh-menubar-max-w, var(--xh-overlay-max-w));
+    /* 静态档与落位后的可用宽度取小：窄视口下面板伸出去，最右侧的内容就点不到了 */
+    max-inline-size: min(var(--xh-menubar-max-w, var(--xh-overlay-max-w)), var(--xh-_menubar-available-w));
     /* 两道上限取更小的那道：自己的高度上限，以及落定那一侧真正剩下的空间。
        列表族的 16rem 对命令菜单偏矮，这里另给一档 */
     max-block-size: min(var(--xh-menubar-max-h, var(--xh-overlay-menu-max-h)), var(--xh-_menubar-available-h));
-    padding-block: var(--xh-menubar-py, var(--xh-space-1));
-    padding-inline: var(--xh-menubar-px, var(--xh-space-1));
-    border: var(--xh-stroke-thin) solid var(--xh-menubar-border, var(--xh-border-default));
-    border-radius: var(--xh-menubar-radius, var(--xh-shape-surface));
-    background: var(--xh-menubar-bg, var(--xh-bg-surface));
-    color: var(--xh-menubar-fg, var(--xh-fg-default));
-    box-shadow: var(--xh-menubar-shadow, var(--xh-elevation-floating));
-    /* 条目超过上限就在菜单内部滚。条目的焦点环是内收的，滚动容器裁在内边距缘上，环切不着 */
+    padding-block: var(--xh-menubar-content-py, var(--xh-surface-pad-xs));
+    padding-inline: var(--xh-menubar-content-px, var(--xh-surface-pad-xs));
+    border: var(--xh-stroke-thin) solid var(--xh-menubar-border, var(--xh-material-frosted-border));
+    border-radius: var(--xh-menubar-content-radius, var(--xh-shape-overlay));
+    background: var(--xh-menubar-content-bg, var(--xh-material-frosted-bg));
+    color: var(--xh-menubar-content-fg, var(--xh-material-frosted-fg));
+    box-shadow: var(--xh-menubar-content-shadow, var(--xh-material-frosted-shadow));
+    -webkit-backdrop-filter: var(--xh-menubar-backdrop, var(--xh-material-frosted-backdrop));
+    backdrop-filter: var(--xh-menubar-backdrop, var(--xh-material-frosted-backdrop));
+    /* 条目超过上限就在菜单内部滚。条目的焦点环是内收的，滚动容器裁在内边距缘上，环切不着。
+       浮层滚动面：到底后不把滚动链穿透给页面（§6.6） */
     overflow-y: auto;
+    overscroll-behavior: contain;
     pointer-events: auto;
   }
 
+  /* 顶光叠在真实四边 border 内侧；强制色撤掉装饰后，完整轮廓仍然存在。 */
+  [data-scope='menubar'][data-part='content']::before {
+    content: '';
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline: 0;
+    block-size: var(--xh-stroke-thin);
+    border-radius: inherit;
+    background: var(--xh-menubar-highlight, var(--xh-material-frosted-highlight));
+    pointer-events: none;
+  }
+
   /* display 会盖掉 hidden 属性的 UA 规则，收起态显式让位。
      连接层给 content 发 hidden，这一条漏了整张菜单就永远收不起来 */
   /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
@@ -181,19 +215,20 @@
     outline: none;
   }
 
-  /* 展开时轻微涨开。只在切换到别张菜单时不重播——那由 data-state 的翻转天然保证：
-     一张关一张开，动画各跑各的 */
+  /* 首开从锚点一侧淡入短移，不缩放整张菜单面。 */
   [data-scope='menubar'][data-part='content'][data-state='open'] {
-    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    /* 在场那一档才提前备好合成层：属性随 data-state 一起消失，收起后不长期占着 */
+    will-change: opacity, translate;
+    animation: xh-overlay-slide-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
   }
 
-  /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来 */
+  /* 末收向锚点一侧淡出；forwards 防止动画完成到真正隐藏之间闪回原样。 */
   [data-scope='menubar'][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;
   }
 
-  /* 在一排入口间换张时两侧都瞬时：交叉淡变读起来就是闪烁，且退场关键帧从不透明度 1
-     起跳，打断未播完的进场还会亮一下。原生菜单栏的成规——首开有进场、末收有退场、
+  /* 在一排入口间换张时两侧都瞬时：交叉淡变读起来就是闪烁。原生菜单栏的成规——首开有进场、末收有退场、
      换张不播。没有动画时退场闸门当场落定，收起即藏 */
   [data-scope='menubar'][data-part='content'][data-instant] {
     animation: none;
@@ -215,7 +250,7 @@
     display: block;
     padding-block: var(--xh-menubar-group-label-py, var(--xh-space-1));
     padding-inline: var(--xh-menubar-group-label-px, var(--xh-_menubar-item-px));
-    color: var(--xh-menubar-group-label-fg, var(--xh-fg-subtle));
+    color: var(--xh-menubar-group-label-fg, var(--xh-material-frosted-fg-muted));
     font-size: var(--xh-menubar-group-label-font-size, var(--xh-text-caption-size));
     font-weight: var(--xh-menubar-group-label-font-weight, var(--xh-font-weight-medium));
     line-height: var(--xh-leading-none);
@@ -226,22 +261,34 @@
     display: none;
   }
 
+  /* 条目走 Collection Item 的 overlay 语境：悬停 / 键盘锚点（data-highlighted，白底承载 100）、按下（200）、
+     子层开着的打开路径（data-in-path，与 hover 同档）与禁用面（aria-disabled）都由家族给，这里只把公开槽映射到
+     桥接槽。布局保持 flex 而不用家族网格：图标、正文、快捷键按一行排布，说明另起一行靠 flex-wrap 折下去，
+     子菜单箭头是行尾的伪元素；间距统一由行的 gap 给，家族按槽下发的外边距归零 */
   [data-scope='menubar'][data-part='item'] {
+    --xh-collection-block-padding: var(--xh-menubar-item-py, var(--xh-_menubar-item-py));
+    --xh-collection-inline-padding: var(--xh-menubar-item-px, var(--xh-_menubar-item-px));
+    --xh-collection-gap: 0;
+    --xh-collection-font-size: var(--xh-menubar-item-font-size, var(--xh-_menubar-font-size));
+    --xh-collection-radius: var(--xh-menubar-item-radius, var(--xh-shape-control));
+    --xh-collection-fg-rest: var(--xh-menubar-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-hover: var(--xh-menubar-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-keyboard-highlight: var(--xh-menubar-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-pressed: var(--xh-menubar-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-open-path: var(--xh-menubar-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-bg-hover: var(--xh-menubar-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-keyboard-highlight: var(--xh-menubar-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-pressed: var(--xh-menubar-item-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-bg-open-path: var(--xh-menubar-item-bg-active, var(--xh-bg-subtle));
+    /* data-highlighted 同时覆盖指针与键盘路径：指针只换面，焦点环在 :focus-visible 下再接回 */
+    --xh-collection-outline-keyboard-highlight: transparent;
+
     display: flex;
     align-items: center;
     gap: var(--xh-menubar-item-gap, var(--xh-_menubar-item-gap));
-    padding-block: var(--xh-menubar-item-py, var(--xh-_menubar-item-py));
-    padding-inline: var(--xh-menubar-item-px, var(--xh-_menubar-item-px));
-    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-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 就得补这条 */
@@ -249,27 +296,25 @@
     display: none;
   }
 
-  /* 悬停与键盘锚点共用中性灰轻档：锚点只认连接层打的 data-highlighted，不读 :focus */
-  [data-scope='menubar'][data-part='item']:not([data-disabled]):is(:hover, [data-highlighted]) {
-    background: var(--xh-menubar-item-bg-hover, var(--xh-bg-subtle));
-  }
+  /* 键盘焦点出现时环才接回并立即到位，不压在背景过渡的中间帧上 */
+  [data-scope='menubar'][data-part='item']:focus-visible:not(:hover) {
+    --xh-collection-outline-keyboard-highlight: var(--xh-ring-focus);
 
-  /* 打开子菜单的触发条目是展开路径，走品牌淡底加粗强档。
-     必须排在轻档之后：悬停或焦点回到它身上时同特指度靠书写顺序压过轻档 */
-  [data-scope='menubar'][data-part='item']:not([data-disabled])[data-state='open'] {
-    background: var(--xh-menubar-item-bg-active, var(--xh-_menubar-item-active-bg));
-    font-weight: var(--xh-menubar-item-active-font-weight, var(--xh-font-weight-semibold));
+    transition: none;
   }
 
   /* 带子菜单的条目行尾画右向小箭头：不点开也看得出还有下一级。
-     位置靠 margin 顶到行尾，图形取兜底字形令牌 */
+     description 按 order 独占下一行，箭头仍留在主行末端。
+     箭头是指示符（§6.5）：与标记位的盒同走 --xh-control-indicator-size，不读 --xh-icon-size——
+     按图标档取的 20px 会比 16px 的标记位盒大一圈 */
   [data-scope='menubar'][data-part='item'][aria-haspopup='menu']::after {
     content: '';
     flex: none;
+    order: 1;
     margin-inline-start: auto;
-    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
-    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
-    background-color: currentColor;
+    inline-size: var(--xh-menubar-submenu-indicator-size, var(--xh-control-indicator-size));
+    block-size: var(--xh-menubar-submenu-indicator-size, var(--xh-control-indicator-size));
+    background-color: var(--xh-menubar-submenu-indicator-fg, var(--xh-material-frosted-fg-muted));
     -webkit-mask: var(--xh-glyph-mark-chevron-right) center / contain no-repeat;
     mask: var(--xh-glyph-mark-chevron-right) center / contain no-repeat;
   }
@@ -280,24 +325,9 @@
     mask-image: var(--xh-glyph-mark-chevron-left);
   }
 
-  /* 键盘落焦的条目画内收环；指针触发的聚焦不画 */
-  [data-scope='menubar'][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='menubar'][data-part='item']:focus:not(:focus-visible) {
-    outline: none;
-  }
-
-  [data-scope='menubar'][data-part='item'][data-disabled] {
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
-  }
-
   [data-scope='menubar'][data-part='item-text'] {
-    display: block;
     flex: 1;
+    min-inline-size: 0;
     overflow: hidden;
     white-space: nowrap;
     text-overflow: ellipsis;
@@ -307,13 +337,20 @@
     display: none;
   }
 
-  /* 标记位（勾选符号 / 图标 / 快捷键提示）：定宽占位，切换内容不引起行宽抖动 */
+  /* 标记位（勾选符号 / 图标）按作者写入的位置留在主行，不为没写的条目强制占列。盒是指示符（§6.5）：按指示符档
+     取尺，与 Menu / ContextMenu 的标记位同走 --xh-control-indicator-size，不读家族按档下发的 --xh-icon-size——
+     按图标档取的 20px 会比同一行 16px 的指示符档大一圈。盒在自己身上把 --xh-icon-size 改接到盒的尺，
+     皮肤画的兜底勾与作者塞进标记位的 XhIcon 读同一把尺、与盒同边长（行尾标记不是勾选格，不取 × 0.75）；
+     条目上那支只管作者直接放进条目里的图标 */
   [data-scope='menubar'][data-part='item-indicator'] {
+    --xh-icon-size: var(--xh-menubar-item-indicator-size, var(--xh-control-indicator-size));
+
     display: inline-flex;
     flex: none;
     align-items: center;
     justify-content: center;
     inline-size: var(--xh-menubar-item-indicator-size, var(--xh-control-indicator-size));
+    block-size: var(--xh-menubar-item-indicator-size, var(--xh-control-indicator-size));
     color: var(--xh-menubar-item-indicator-fg, var(--xh-_tone, var(--xh-fg-brand)));
   }
 
@@ -325,15 +362,55 @@
     color: var(--xh-fg-disabled);
   }
 
+  /* 副文本另起一行：整行占满，把条目的一行内容折成两行 */
+  [data-scope='menubar'][data-part='item-description'] {
+    flex: 1 0 100%;
+    order: 2;
+    min-inline-size: 0;
+    color: var(--xh-menubar-item-description-fg, var(--xh-material-frosted-fg-muted));
+    font-size: var(--xh-menubar-item-description-font-size, var(--xh-text-caption-size));
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    overflow: hidden;
+  }
+
+  [data-scope='menubar'][data-part='item-description'][hidden] {
+    display: none;
+  }
+
+  [data-scope='menubar'][data-part='item-description'][data-disabled] {
+    color: var(--xh-fg-disabled);
+  }
+
+  /* 没有说明时主行不允许无意换行；有说明才开启第二行。任意图标/快捷键仍保留作者的 DOM 顺序。 */
+  [data-scope='menubar'][data-part='item']:has(> [data-scope='menubar'][data-part='item-description']) {
+    flex-wrap: wrap;
+  }
+
+  /* 箭头的底色与描边色，几何在 overlay-arrow.css。
+     交叉轴落点由定位引擎经内联自定义属性写进来，没给时退回居中 */
+  [data-scope='menubar'][data-part='arrow'] {
+    --xh-_menubar-arrow-x: 50%;
+    --xh-_menubar-arrow-y: 50%;
+    --xh-_overlay-arrow-size: var(--xh-menubar-arrow-size, var(--xh-overlay-arrow-size));
+    --xh-_overlay-arrow-x: var(--xh-_menubar-arrow-x);
+    --xh-_overlay-arrow-y: var(--xh-_menubar-arrow-y);
+
+    background: var(--xh-menubar-content-bg, var(--xh-material-frosted-bg));
+    border: var(--xh-stroke-thin) solid var(--xh-menubar-border, var(--xh-material-frosted-border));
+  }
+
   /* 分隔线横跨菜单，与菜单栏自身的 orientation 无关：菜单永远是一列条目。
      不给 display，因此 UA 的 [hidden]{display:none} 自己就压得住 */
   [data-scope='menubar'][data-part='separator'] {
     block-size: var(--xh-menubar-separator-thickness, var(--xh-stroke-thin));
     margin-block: var(--xh-menubar-separator-my, var(--xh-space-0_5));
-    background: var(--xh-menubar-separator-color, var(--xh-border-default));
+    border-radius: var(--xh-menubar-separator-radius, var(--xh-shape-pill));
+    background: var(--xh-menubar-separator-color, var(--xh-material-frosted-separator));
   }
 
-  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中。
+     尺寸读标记位自己改接过的 --xh-icon-size：与盒同边长，随指示符档换档（见上面标记位那块） */
   [data-scope='menubar'][data-part='item-indicator']:empty::before {
     content: '';
     display: inline-block;
@@ -346,29 +423,20 @@
   }
 }
 
-@layer xihan.motion {
-  /* 自带前缀独占一个名字，不动公共的那份关键帧 */
-  @keyframes xh-pop-in {
-    from {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
-
-    to {
-      opacity: 1;
-      scale: 1;
+@layer xihan.components {
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    [data-scope='menubar'][data-part='positioner'] {
+      display: none;
     }
   }
 
-  @keyframes xh-pop-out {
-    from {
-      opacity: 1;
-      scale: 1;
-    }
-
-    to {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
+  @media (forced-colors: active) {
+    /* 分组之间那条线画的是一块纯底色，这一档里底色被统一换成 Canvas，线整条消失，
+       几组条目就连成了一长串。换成前景色画回来 */
+    [data-scope='menubar'][data-part='separator'] {
+      background: CanvasText;
     }
   }
 }