@xihan-ui/styles 1.0.0 → 2.0.0

package/css/kbd.css

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 kbd 样式。 */
+
+@layer xihan.components {
+  [data-scope='kbd'] {
+    --xh-kbd-skin: 1;
+  }
+
+  /* 单键和组合键共用一个整体表面，不模拟按钮按下状态。 */
+  [data-scope='kbd'][data-part='root'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--xh-kbd-gap, var(--xh-space-1));
+    box-sizing: border-box;
+    block-size: var(--xh-kbd-h, var(--xh-space-6));
+    min-inline-size: var(--xh-kbd-min-w, var(--xh-space-6));
+    padding-inline: var(--xh-kbd-px, var(--xh-space-2));
+    border: var(--xh-stroke-thin) solid var(--xh-kbd-border, transparent);
+    border-radius: var(--xh-kbd-radius, var(--xh-shape-control));
+    background: var(--xh-kbd-bg, var(--xh-bg-subtle));
+    color: var(--xh-kbd-fg, var(--xh-fg-muted));
+    font-family: var(--xh-kbd-font, inherit);
+    /* 快捷键是次级标注，字号取 caption 档（§6.4） */
+    font-size: var(--xh-kbd-font-size, var(--xh-text-caption-size));
+    font-weight: var(--xh-kbd-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+    text-align: center;
+    text-decoration: none;
+    white-space: nowrap;
+    direction: ltr;
+    unicode-bidi: isolate;
+  }
+
+  [data-scope='kbd'][data-part='root'][data-variant='light'] {
+    background: transparent;
+  }
+
+  [data-scope='kbd'][data-part='key'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-inline-size: 0;
+    padding: 0;
+    border: 0;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    line-height: inherit;
+  }
+
+  [data-scope='kbd'][data-part='root'][data-disabled] {
+    color: var(--xh-kbd-fg-disabled, var(--xh-fg-disabled));
+  }
+
+  [data-scope='kbd'][data-part='root'][hidden],
+  [data-scope='kbd'][data-part='key'][hidden] {
+    display: none;
+  }
+
+  @media (forced-colors: active) {
+    [data-scope='kbd'][data-part='root']:not([data-variant='light']) {
+      border-color: ButtonText;
+      background: Canvas;
+      color: CanvasText;
+    }
+  }
+}

package/css/label.css

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/*
+ * 字段族标签的公共层，按 [data-part='label'] 匹配下面逐个列出的 scope。
+ *
+ * 收在这里的是逐值相同的四条：行距取 --xh-leading-none，禁用档字色取 --xh-fg-subtle，
+ * 必填星号取 --xh-glyph-mark-required + --xh-space-1 + --xh-fg-danger，无效档字色取 --xh-fg-danger。
+ * 字色、字号、字重三条留在各组件皮肤——它们挂着 --xh-<组件>-label-* 覆盖槽，
+ * 槽名里带组件名，写不进一条共享规则。
+ *
+ * scope 逐个列出，不写成 [data-scope][data-part='label']：label 这个部件名在标签、
+ * 统计、进度、推理、说明列表上指的是另一种文字（行内省略的标签正文、环内居中的数字、
+ * 描述项的名字），通配规则会把行距按到它们头上。要接进来的组件把 scope 加进列表。
+ *
+ * 选择器停在两个属性（0,2,0）或三个属性（0,3,0），与组件皮肤同级；引入顺序排在全部组件皮肤之前，
+ * 要另写行距的组件照写即可压过。
+ */
+@layer xihan.components {
+  /* 标签是单行短文，行距不留额外的行间空白，标签与控件之间只剩容器给的那一道间距。 */
+  [data-scope='checkbox'][data-part='label'],
+  [data-scope='checkbox-group'][data-part='label'],
+  [data-scope='color-picker'][data-part='label'],
+  [data-scope='date-field'][data-part='label'],
+  [data-scope='editable'][data-part='label'],
+  [data-scope='field'][data-part='label'],
+  [data-scope='file-upload'][data-part='label'],
+  [data-scope='number-field'][data-part='label'],
+  [data-scope='password-input'][data-part='label'],
+  [data-scope='pin-input'][data-part='label'],
+  [data-scope='radio-group'][data-part='label'],
+  [data-scope='rating'][data-part='label'],
+  [data-scope='signature-pad'][data-part='label'],
+  [data-scope='slider'][data-part='label'],
+  [data-scope='switch'][data-part='label'],
+  [data-scope='tags-input'][data-part='label'],
+  [data-scope='text-field'][data-part='label'],
+  [data-scope='time-field'][data-part='label'] {
+    line-height: var(--xh-leading-none);
+  }
+
+  /*
+   * 禁用档的字色：公共层默认统一 --xh-fg-subtle。这四家没有 --xh-<组件>-label-fg-disabled 覆盖槽，
+   * 取值只有这一处；挂了那个槽的组件在各自皮肤里另写一条，排在本份之后，压过这里。
+   */
+  [data-scope='color-picker'][data-part='label'][data-disabled],
+  [data-scope='rating'][data-part='label'][data-disabled],
+  [data-scope='signature-pad'][data-part='label'][data-disabled],
+  [data-scope='slider'][data-part='label'][data-disabled] {
+    color: var(--xh-fg-subtle);
+  }
+
+  /*
+   * 必填星号：跟着标签自己的 data-required 亮，选填不标。字形、间距、颜色是公共层规则，
+   * 自带标签的字段不得各画一套。
+   *
+   * 接入 = connect 在标签部件投影 data-required + 把 scope 加进这张列表；控件本体不画。
+   * 有 --xh-<组件>-label-star 覆盖槽的组件在各自皮肤里只另写一条 color 压过这里（field 的
+   * --xh-field-label-star、fieldset 的 --xh-fieldset-legend-star），content 与间距不再重写。
+   */
+  [data-scope='field'][data-part='label'][data-required]::after,
+  [data-scope='fieldset'][data-part='legend'][data-required]::after {
+    content: var(--xh-glyph-mark-required);
+    margin-inline-start: var(--xh-space-1);
+    color: var(--xh-fg-danger);
+  }
+
+  /*
+   * 无效档的字色：标签跟着自己的 data-invalid 转警示色，没渲染错误文案的字段上这是唯一变化的东西。
+   * 有 --xh-<组件>-label-fg-invalid 覆盖槽的组件在各自皮肤里另写一条 color 压过这里。
+   */
+  [data-scope='field'][data-part='label'][data-invalid],
+  [data-scope='fieldset'][data-part='legend'][data-invalid] {
+    color: var(--xh-fg-danger);
+  }
+}

package/css/layers.css

@@ -1,2 +1,7 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
 /* 库层序单一真源：级联顺序由首次声明决定，与 @import 顺序解耦。 */
 @layer xihan.reset, xihan.tokens, xihan.motion, xihan.components, xihan.overrides;

package/css/layout.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.
+ */
+
+/* 定义 layout 样式。 */
+
+/* 独立皮肤传递引入折叠把手的动作控件配方，full bundle 递归去重。 */
+@import '../family/action-control.css';
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='layout'] {
@@ -8,6 +18,7 @@
      缺哪一段，对应的行/列就没有条目，宽高自动收成 0，不必为"少写一段"另立规则。
 
      侧栏两档宽度与头的高度声明在根上：各段自己读这些槽，换档只改这里。
+     宽度槽用 -w 缩写，与同处的 --xh-layout-header-h 一致。
      头的高度之所以也归到根上：头吸顶时头这一行的轨道要按同一个值定高，两处必须同源。 */
   [data-scope='layout'][data-part='root'] {
     display: grid;
@@ -17,15 +28,49 @@
       'footer footer';
     grid-template-columns: auto minmax(0, 1fr);
     grid-template-rows: auto minmax(0, 1fr) auto;
-    background: var(--xh-layout-bg, var(--xh-bg-canvas));
+    background: var(--xh-layout-bg, var(--xh-bg-page));
     color: var(--xh-layout-fg, var(--xh-fg-default));
-    --xh-_layout-sider-w: var(--xh-layout-sider-width, 15rem);
-    --xh-_layout-sider-collapsed-w: var(--xh-layout-sider-collapsed-width, 4rem);
+    --xh-_layout-sider-expanded-w: var(--xh-layout-sider-w, 15rem);
+    --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    --xh-_layout-sider-collapsed-w: var(--xh-layout-sider-collapsed-w, 4rem);
     --xh-_layout-header-h: var(--xh-layout-header-h, 3.5rem);
     /* 侧栏吸附时钉在哪条线上：缺省贴滚动容器上沿，头也吸顶时改成让开头的高度 */
     --xh-_layout-sider-offset: 0px;
   }
 
+  /* —— 侧栏断点 —— */
+  /* 写了断点档就先按窄屏排（折叠宽），视口宽到那一档再还原成展开宽。
+     移动优先、四档只用 min-width：媒体查询不改选择器权重，同时命中好几档时由源码序决定谁生效。
+     宽度写字面量：自定义属性在 @media 条件里不参与求值，令牌变量写在这里等于没写条件。
+     换的只是宽度，折叠态不动——那条通道归 siderCollapsed。 */
+  [data-scope='layout'][data-part='root'][data-sider-breakpoint] {
+    --xh-_layout-sider-w: var(--xh-_layout-sider-collapsed-w);
+  }
+
+  @media (min-width: 640px) {
+    [data-scope='layout'][data-part='root'][data-sider-breakpoint='sm'] {
+      --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    }
+  }
+
+  @media (min-width: 768px) {
+    [data-scope='layout'][data-part='root'][data-sider-breakpoint='md'] {
+      --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    }
+  }
+
+  @media (min-width: 1024px) {
+    [data-scope='layout'][data-part='root'][data-sider-breakpoint='lg'] {
+      --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    }
+  }
+
+  @media (min-width: 1280px) {
+    [data-scope='layout'][data-part='root'][data-sider-breakpoint='xl'] {
+      --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    }
+  }
+
   /* 侧栏挂到行尾：两列对调，内容在前 */
   [data-scope='layout'][data-part='root'][data-sider-placement='end'] {
     grid-template-areas:
@@ -46,14 +91,19 @@
     background: var(--xh-layout-header-bg, var(--xh-bg-surface));
   }
 
-  /* 宽度过渡在这里声明一次，展开与折叠两档、以及 props 直接写进内联的宽度，走的都是这一条 */
+  /* 宽度过渡在这里声明一次，展开与折叠两档、以及 props 直接写进内联的宽度，走的都是这一条。
+     占位档的侧栏是淡底承载面：把手摆进来时由它下发 hover 200 → pressed 300（§7.2）；
+     覆盖档换成 elevated 白底，那一档的规则把阶梯写回 100 → 200 */
   [data-scope='layout'][data-part='sider'] {
+    --xh-action-host-bg-hover: var(--xh-bg-subtle-hover);
+    --xh-action-host-bg-pressed: var(--xh-bg-subtle-active);
+
     grid-area: sider;
     inline-size: var(--xh-_layout-sider-w);
     overflow: hidden;
     padding: var(--xh-layout-sider-padding, var(--xh-space-3));
     background: var(--xh-layout-sider-bg, var(--xh-bg-subtle));
-    transition: inline-size var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    transition: inline-size var(--xh-motion-duration-enter) var(--xh-motion-ease-continuous);
   }
 
   /* 折起来时不换行：窄到放不下的那几个字直接被 overflow 裁掉，不会挤成一列竖排 */
@@ -78,47 +128,38 @@
   }
 
   /* —— 折叠把手 —— */
+  /* 一枚小档文字按钮：盒型、悬停 / 按下面与按压缩放由 Action Control 的 text 档给（ghost 形态，sm 档：
+     摆在顶栏等白底上按画布承载 hover 100 → pressed 200，摆进占位档侧栏时由侧栏下发 host 槽 200 → 300，
+     覆盖档侧栏是 elevated 白底、仍是 100 → 200）；
+     这里只把使用者槽映射到桥接槽（-gap / -px / -radius / -bg / -bg-hover / -bg-active / -fg 保留为第一参数） */
   [data-scope='layout'][data-part='sider-trigger'] {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    gap: var(--xh-layout-sider-trigger-gap, var(--xh-control-gap-sm));
-    block-size: var(--xh-control-h-sm);
-    padding-inline: var(--xh-layout-sider-trigger-px, var(--xh-control-px-sm));
-    border: 0;
-    border-radius: var(--xh-layout-sider-trigger-radius, var(--xh-shape-control));
-    background: var(--xh-layout-sider-trigger-bg, transparent);
-    color: var(--xh-layout-sider-trigger-fg, var(--xh-fg-default));
-    font-size: var(--xh-text-secondary-size);
-    line-height: var(--xh-leading-none);
-    cursor: pointer;
-  }
-
-  [data-scope='layout'][data-part='sider-trigger']:hover {
-    background: var(--xh-layout-sider-trigger-bg-hover, var(--xh-bg-subtle-hover));
-  }
-
-  [data-scope='layout'][data-part='sider-trigger']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
+    --xh-action-gap: var(--xh-layout-sider-trigger-gap, var(--xh-_action-profile-gap));
+    --xh-action-padding-inline: var(--xh-layout-sider-trigger-px, var(--xh-_action-profile-padding-inline));
+    --xh-action-radius: var(--xh-layout-sider-trigger-radius, var(--xh-_action-profile-radius));
+    --xh-action-bg-rest: var(--xh-layout-sider-trigger-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-layout-sider-trigger-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-layout-sider-trigger-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-layout-sider-trigger-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-layout-sider-trigger-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-layout-sider-trigger-fg, var(--xh-_action-variant-fg-pressed));
   }
 
   /* —— 分隔线 —— */
   /* 后代选择器带上 data-scope：骨架里装着整页内容，光凭 data-part 会连里面别的组件同名段一起画上线 */
-  [data-scope='layout'][data-part='root'][data-bordered] [data-scope='layout'][data-part='header'] {
+  [data-scope='layout'][data-part='root'][data-split] [data-scope='layout'][data-part='header'] {
     border-block-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
   }
 
-  [data-scope='layout'][data-part='root'][data-bordered] [data-scope='layout'][data-part='footer'] {
+  [data-scope='layout'][data-part='root'][data-split] [data-scope='layout'][data-part='footer'] {
     border-block-start: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
   }
 
   /* 侧栏只在挨着内容的那一边画线，另一边贴着骨架外沿，画了就是一条多出来的边框 */
-  [data-scope='layout'][data-part='root'][data-bordered] [data-scope='layout'][data-part='sider'][data-placement='start'] {
+  [data-scope='layout'][data-part='root'][data-split] [data-scope='layout'][data-part='sider'][data-placement='start'] {
     border-inline-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
   }
 
-  [data-scope='layout'][data-part='root'][data-bordered] [data-scope='layout'][data-part='sider'][data-placement='end'] {
+  [data-scope='layout'][data-part='root'][data-split] [data-scope='layout'][data-part='sider'][data-placement='end'] {
     border-inline-start: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
   }
 
@@ -168,6 +209,109 @@
     overflow-y: auto;
   }
 
+  /* —— 侧栏覆盖档 —— */
+  /* 侧栏移出画外、盖在内容之上：面板脱离网格，侧栏那一列于是收成零宽，内容占满整行。
+     排在固定定位那一节之后：两处特指度相同，覆盖档要盖住 sticky 那一档。
+     参照的是视口，与上面 sticky 那条同一个注意事项：整副骨架装进带 transform / filter 的祖先里时，
+     固定定位的包含块会换成那个祖先，面板跟着一起滚。 */
+  [data-scope='layout'][data-part='sider'][data-presentation='sheet'] {
+    /* 位移方向的私有槽位：默认按行首 + LTR，行尾与 RTL 在下面翻符号。
+       写成槽位而不是写死 ±100%：贴边用的是逻辑 inset，RTL 下行首落在物理右边，
+       位移若写死物理方向就会出现「贴在右边、却从左边滑进来」 */
+    --xh-_layout-sheet-shift: -100%;
+    /* 这一档的底是 elevated 白底：交互阶梯按承载面走（§7.2），把上面占位档下发的 200 → 300 写回
+       白底的 hover 100 → pressed 200 */
+    --xh-action-host-bg-hover: var(--xh-bg-subtle);
+    --xh-action-host-bg-pressed: var(--xh-bg-subtle-hover);
+
+    position: fixed;
+    z-index: var(--xh-layout-sider-layer, var(--xh-layer-drawer));
+    inset-block: 0;
+    inset-inline-start: 0;
+    inset-inline-end: auto;
+    inline-size: var(--xh-_layout-sider-expanded-w);
+    /* 面板贴死上下两条边，高度上限就是滚动容器可视区那么高——上面 sticky 那一档的
+       「减去顶栏偏移」在这一档不作数：覆盖档从视口顶铺到底。
+       不认 dvh 的引擎由级联回落到前一条的 vh */
+    max-block-size: var(--xh-layout-scrollport-h, 100vh);
+    max-block-size: var(--xh-layout-scrollport-h, 100dvh);
+    /* 贴死视口的那一档，内衬与安全区取大的一头：刘海、圆角与底部横条压住的那一段由系统给出。
+       桌面上 env() 恒为 0，取值与内衬槽完全一致。安全区只有物理方向的四个名字，
+       行内轴上两侧同取较宽的那一段，RTL 下不会翻错边 */
+    padding-block-start: max(var(--xh-layout-sider-padding, var(--xh-space-3)), env(safe-area-inset-top));
+    padding-block-end: max(var(--xh-layout-sider-padding, var(--xh-space-3)), env(safe-area-inset-bottom));
+    padding-inline: max(
+      var(--xh-layout-sider-padding, var(--xh-space-3)),
+      env(safe-area-inset-left),
+      env(safe-area-inset-right)
+    );
+    /* 盖在内容之上、带遮罩的一面走 sheet 三件套（§8.4：--xh-material-elevated-bg / -border / -shadow），
+       贴着内容那一侧描一条边；占位档的侧栏不画投影 */
+    border-inline-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-material-elevated-border));
+    background: var(--xh-layout-sider-bg, var(--xh-material-elevated-bg));
+    box-shadow: var(--xh-layout-sider-shadow, var(--xh-material-elevated-shadow));
+    translate: 0 0;
+    visibility: visible;
+    /* 条目多到装不下时在面板内部滚：这一档的高度就是视口那么高。
+       overscroll 不在这里写 contain：这一面与占位档共用同一个部件，scroll-surface-registry 把侧栏整体登记为
+       页内结构容器（overscroll=false），门禁按整个部件核，不按档分 */
+    overflow-y: auto;
+    /* 推出来与收进去是同一段行程，视口尺度的位移走 slide 档。
+       visibility 与它同拍：收起那一路等位移播完才真正藏起来，展开那一路立刻露出来 */
+    transition:
+      translate var(--xh-motion-duration-slide) var(--xh-motion-ease-slide),
+      visibility var(--xh-motion-duration-slide) var(--xh-motion-ease-slide);
+  }
+
+  /* 挂在行尾：贴另一条边，位移随之反向，描边也换到贴着内容的那一侧 */
+  [data-scope='layout'][data-part='sider'][data-presentation='sheet'][data-placement='end'] {
+    --xh-_layout-sheet-shift: 100%;
+
+    inset-inline-start: auto;
+    inset-inline-end: 0;
+    border-inline-end: 0;
+    border-inline-start: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-material-elevated-border));
+  }
+
+  [data-scope='layout'][data-part='sider'][data-presentation='sheet']:dir(rtl) {
+    --xh-_layout-sheet-shift: 100%;
+  }
+
+  [data-scope='layout'][data-part='sider'][data-presentation='sheet'][data-placement='end']:dir(rtl) {
+    --xh-_layout-sheet-shift: -100%;
+  }
+
+  /* 收起：推出画外并让出无障碍树与 Tab 序列。位移量按面板自身宽度的百分比算，
+     宽度换成任何一档都正好推到画外 */
+  [data-scope='layout'][data-part='sider'][data-presentation='sheet'][data-collapsed] {
+    translate: var(--xh-_layout-sheet-shift) 0;
+    visibility: hidden;
+  }
+
+  /* 覆盖档的遮罩：与面板同一个层号，谁盖谁看文档序——遮罩写在侧栏之前。
+     占位档下连接层给它打 hidden，这里不必再管 */
+  [data-scope='layout'][data-part='sider-backdrop'] {
+    position: fixed;
+    z-index: var(--xh-layout-sider-backdrop-layer, var(--xh-layer-drawer));
+    inset: 0;
+    background: var(--xh-layout-sider-backdrop-bg, var(--xh-bg-overlay));
+    opacity: 1;
+    transition: opacity var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 收起态：淡出并让开指针，底下的内容照常点得到 */
+  [data-scope='layout'][data-part='sider-backdrop'][data-collapsed] {
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  /* 纸上没有覆盖这回事：遮罩印出来就是盖住正文的一片灰 */
+  @media print {
+    [data-scope='layout'][data-part='sider-backdrop'] {
+      display: none;
+    }
+  }
+
   /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
      写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
   [data-scope='layout'][data-part='root'][hidden],

package/css/list.css

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 list 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='list'] {
@@ -12,6 +19,8 @@
     --xh-_list-item-gap: var(--xh-space-3);
     --xh-_list-title-size: var(--xh-control-font-md);
     --xh-_list-description-size: var(--xh-control-caption-md);
+    /* 条目悬停换到的面：坐在白底上是 100，淡底档的根把它抬到 200（§7.2 按承载面的阶梯） */
+    --xh-_list-item-bg-hover: var(--xh-bg-subtle);
 
     display: flex;
     flex-direction: column;
@@ -41,10 +50,11 @@
     --xh-_list-item-px: var(--xh-list-item-px-lg);
     --xh-_list-item-gap: var(--xh-space-4);
     --xh-_list-title-size: var(--xh-control-font-lg);
+    --xh-_list-description-size: var(--xh-control-caption-lg);
   }
 
-  /* —— 外框 —— */
-  [data-scope='list'][data-part='root'][data-bordered] {
+  /* —— 形态：ghost 即基础规则，不画壳 —— */
+  [data-scope='list'][data-part='root'][data-variant='outline'] {
     border: var(--xh-stroke-thin) solid var(--xh-list-border, var(--xh-border-default));
     border-radius: var(--xh-list-radius, var(--xh-shape-surface));
     background: var(--xh-list-bg, var(--xh-bg-surface));
@@ -52,6 +62,17 @@
     overflow: hidden;
   }
 
+  /* 淡底档：底换成 subtle，描边留一圈透明边位，与 outline 同一几何；
+     条目坐在淡底上，悬停面抬一档 */
+  [data-scope='list'][data-part='root'][data-variant='subtle'] {
+    --xh-_list-item-bg-hover: var(--xh-bg-subtle-hover);
+
+    border: var(--xh-stroke-thin) solid transparent;
+    border-radius: var(--xh-list-radius, var(--xh-shape-surface));
+    background: var(--xh-list-bg, var(--xh-bg-subtle));
+    overflow: hidden;
+  }
+
   /* —— 条目 —— */
   [data-scope='list'][data-part='item'] {
     display: flex;
@@ -76,7 +97,7 @@
   /* 悬停换底色：只在能用指针的设备上生效，触摸端不留一个按不掉的悬停态 */
   @media (hover: hover) {
     [data-scope='list'][data-part='root'][data-hoverable] > [data-scope='list'][data-part='item']:hover {
-      background: var(--xh-list-item-bg-hover, var(--xh-bg-subtle-hover));
+      background: var(--xh-list-item-bg-hover, var(--xh-_list-item-bg-hover));
     }
   }