@xihan-ui/styles 1.0.0 → 2.0.0

package/css/cascader.css

@@ -1,3 +1,16 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* Cascader 独立皮肤同时传递引入字段视觉盒、字段内动作与浮层集合行；full bundle 递归去重。 */
+@import '../family/field-chrome.css';
+@import '../family/action-control.css';
+@import '../family/collection-item.css';
+
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='cascader'] {
@@ -6,11 +19,20 @@
 
   /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
   [data-scope='cascader'][data-part='positioner'] {
+    /* 落定那一侧的可用宽度，由定位引擎经内联自定义属性写进来，列区据此夹住行内轴；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时退到视口宽 */
+    --xh-_cascader-available-w: 100vw;
+    /* 当前浮层只接受自己的落位方向，不叠加祖先的位移。 */
+    --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-cascader-layer, var(--xh-layer-popover));
+    z-index: var(--xh-cascader-layer, var(--xh-_layer, var(--xh-layer-popover)));
     /* 空壳不吃指针，交互只发生在 content 里 */
     pointer-events: none;
   }
@@ -20,34 +42,42 @@
     visibility: hidden;
   }
 
+  /* 位移遵循实际落位的物理方向，不随书写方向翻转。 */
+  [data-scope='cascader'][data-part='positioner'][data-placement^='top'] {
+    --xh-_overlay-enter-down: 1;
+  }
+
+  [data-scope='cascader'][data-part='positioner'][data-placement^='bottom'] {
+    --xh-_overlay-enter-up: 1;
+  }
+
+  [data-scope='cascader'][data-part='positioner'][data-placement^='left'] {
+    --xh-_overlay-enter-right: 1;
+  }
+
+  [data-scope='cascader'][data-part='positioner'][data-placement^='right'] {
+    --xh-_overlay-enter-left: 1;
+  }
+
   /* 私有槽同时声明在根与 positioner 上：浮层被搬到 portal 落点，不是根的后代，继承不过去 */
   [data-scope='cascader']:is([data-part='root'], [data-part='positioner']) {
-    /* 作者塞进指示符槽的图标跟着尺寸档走，与皮肤画的兜底字形同一把尺 */
+    /* 作者塞进触发器指示符槽的图标跟着尺寸档走，与皮肤画的兜底字形同一把尺；列里条目的由家族随
+       data-xh-collection-size 下发（§6.5）。级联选择器自绘的状态字形（标记盒里的勾与半选杠、分支箭头）
+       不读这支：它们是指示符，走 --xh-control-indicator-* 一族——标记盒在自己身上把 --xh-icon-size 改接到
+       盒的尺，分支箭头走 --xh-cascader-branch-arrow-size */
     --xh-icon-size: var(--xh-cascader-icon-size, var(--xh-glyph-size-md));
 
-    /* 尺寸档只换这几个私有槽，盒与列里的条目都从这两处继承它们，换档不必给每个部件各写一条选择器 */
+    /* 尺寸档只换这几个私有槽，盒与列里的条目都从这两处继承它们，换档不必给每个部件各写一条选择器；
+       形态三档由家族按 control 上的 data-variant 生成，浮层与列不跟着变，皮肤不再声明 */
     --xh-_cascader-h: var(--xh-control-h-md);
     --xh-_cascader-px: var(--xh-control-px-md);
     --xh-_cascader-row-py: var(--xh-list-option-py-md);
     --xh-_cascader-row-px: var(--xh-control-px-md);
     --xh-_cascader-gap: var(--xh-control-gap-md);
     --xh-_cascader-font-size: var(--xh-control-font-md);
-    --xh-_cascader-label-font-size: var(--xh-control-font-md);
-
-    /* 形态档只换触发框的描边与底色这三个槽，浮层与列不跟着变：
-       变的是「这是个输入位」的表达方式，不是弹出内容的表达方式 */
-    --xh-_cascader-border: var(--xh-border-control);
-    --xh-_cascader-border-hover: var(--xh-border-control-hover);
-    --xh-_cascader-bg: var(--xh-bg-canvas);
-
-    /* 选中条目的文字色随语气走，没写 data-tone 时退回品牌强调色 */
-    --xh-_cascader-selected-fg: var(--xh-_tone-fg, var(--xh-fg-brand-strong));
-
-    /* 展开路径的底色：随语气走淡底，没写 data-tone 时退回品牌淡底 */
-    --xh-_cascader-active-bg: var(--xh-_tone-subtle, var(--xh-bg-brand-subtle));
 
-    /* 聚焦环恒用固定环色；校验失败时换成告警环色 */
-    --xh-_cascader-ring: var(--xh-ring-focus);
+    /* 强调色随语气走，只落在勾选标记上；没写 data-tone 时退回品牌色 */
+    --xh-_cascader-accent: var(--xh-_tone, var(--xh-fg-brand));
   }
 
   /* 标签一行、盒一行的两行堆叠 */
@@ -55,6 +85,12 @@
     display: inline-flex;
     flex-direction: column;
     gap: var(--xh-cascader-gap, var(--xh-space-1));
+
+    /* 不传尺寸时一律这么宽，宽度不随内容走；父容器给不出这么宽时整件跟着收，地板同步让步，不越出父容器。
+       地板不高过缺省宽：使用者把缺省宽钉到底线以下时不必再放开底线 */
+    inline-size: var(--xh-cascader-control-w, var(--xh-control-w));
+    min-inline-size: min(var(--xh-cascader-control-w, var(--xh-control-w)), var(--xh-cascader-control-min-w, var(--xh-control-min-w)), 100%);
+    max-inline-size: 100%;
   }
 
   /* 只要声明了 display 就盖掉了 UA 的 [hidden]{display:none}，作者手动收起时要自己还回去 */
@@ -62,29 +98,6 @@
     display: none;
   }
 
-  /* —— 形态 —— */
-  /* 形态只决定描边与底色怎么用；用哪族颜色由 data-tone 决定，没写 tone 就沿用原来的中性配色 */
-  /* outline 就是缺省那一身：描边加画布底，写出来只为让三档并列可读 */
-  [data-scope='cascader']:is([data-part='root'], [data-part='positioner'])[data-variant='outline'] {
-    --xh-_cascader-border: var(--xh-border-control);
-    --xh-_cascader-border-hover: var(--xh-border-control-hover);
-    --xh-_cascader-bg: var(--xh-bg-canvas);
-  }
-
-  /* subtle 是填充式：底色接过「这里能点」的表达，描边随之让位 */
-  [data-scope='cascader']:is([data-part='root'], [data-part='positioner'])[data-variant='subtle'] {
-    --xh-_cascader-border: transparent;
-    --xh-_cascader-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
-    --xh-_cascader-bg: var(--xh-_tone-subtle, var(--xh-bg-subtle));
-  }
-
-  /* 无框：底与常态描边透明，悬停浮出描边，聚焦由焦点环表达 */
-  [data-scope='cascader']:is([data-part='root'], [data-part='positioner'])[data-variant='ghost'] {
-    --xh-_cascader-border: transparent;
-    --xh-_cascader-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
-    --xh-_cascader-bg: transparent;
-  }
-
   /* —— 尺寸 —— */
   /* 缺省档写在上面的基础规则里 */
   [data-scope='cascader']:is([data-part='root'], [data-part='positioner'])[data-size='sm'] {
@@ -95,7 +108,6 @@
     --xh-_cascader-row-px: var(--xh-control-px-sm);
     --xh-_cascader-gap: var(--xh-control-gap-sm);
     --xh-_cascader-font-size: var(--xh-control-font-sm);
-    --xh-_cascader-label-font-size: var(--xh-control-font-sm);
   }
 
   [data-scope='cascader']:is([data-part='root'], [data-part='positioner'])[data-size='lg'] {
@@ -106,71 +118,50 @@
     --xh-_cascader-row-px: var(--xh-control-px-lg);
     --xh-_cascader-gap: var(--xh-control-gap-lg);
     --xh-_cascader-font-size: var(--xh-control-font-lg);
-    --xh-_cascader-label-font-size: var(--xh-control-font-lg);
   }
 
   [data-scope='cascader'][data-part='label'] {
     color: var(--xh-cascader-label-fg, var(--xh-fg-default));
-    font-size: var(--xh-cascader-label-font-size, var(--xh-_cascader-label-font-size));
+    font-size: var(--xh-cascader-label-font-size, var(--xh-text-label-size));
     font-weight: var(--xh-cascader-label-font-weight, var(--xh-text-label-weight));
     line-height: var(--xh-leading-none);
   }
 
   /* 整个控件禁用会把 data-disabled 一路打到 label / value-text / indicator 上，各处观感保持一致 */
   [data-scope='cascader'][data-part='label'][data-disabled] {
-    color: var(--xh-fg-subtle);
+    color: var(--xh-cascader-label-fg-disabled, var(--xh-fg-subtle));
   }
 
-  /* 盒：描边、底色、控件高度与行内内衬都落在这一层，触发按钮与清空按钮在里面并排 */
+  /* 盒：描边、底色、圆角、控件高度、行内内衬、聚焦环、五态与悬停由 Field Chrome 家族画在这一层，
+     触发按钮与清空按钮在里面并排；Tab 停靠点是盒里的 trigger（展开后才移进列里），环由家族的
+     :focus-within 画在盒上。组件只映射既有公开槽（shadow 缺省 none：字段静息描边式、无影）；盒里是按钮 */
   [data-scope='cascader'][data-part='control'] {
-    display: inline-flex;
-    align-items: center;
-    gap: var(--xh-cascader-control-gap, var(--xh-_cascader-gap));
-    min-inline-size: var(--xh-cascader-control-min-w, var(--xh-control-min-w));
-    block-size: var(--xh-cascader-control-h, var(--xh-_cascader-h));
-    padding-inline: var(--xh-cascader-control-px, var(--xh-_cascader-px));
-    border: var(--xh-stroke-thin) solid var(--xh-cascader-control-border, var(--xh-_cascader-border));
-    border-radius: var(--xh-cascader-control-radius, var(--xh-shape-control));
-    background: var(--xh-cascader-control-bg, var(--xh-_cascader-bg));
-    color: var(--xh-cascader-control-fg, var(--xh-fg-default));
-    cursor: pointer;
-    transition: border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+    --xh-field-control-height: var(--xh-cascader-control-h, var(--xh-_cascader-h));
+    --xh-field-control-padding-inline: var(--xh-cascader-control-px, var(--xh-_cascader-px));
+    --xh-field-control-gap: var(--xh-cascader-control-gap, var(--xh-_cascader-gap));
+    --xh-field-control-min-inline-size: var(--xh-cascader-control-min-w, var(--xh-control-min-w));
+    --xh-field-control-radius: var(--xh-cascader-control-radius, var(--xh-shape-control));
+    --xh-field-bg-rest: var(--xh-cascader-control-bg, var(--xh-_field-variant-bg-rest));
+    --xh-field-bg-hover: var(--xh-cascader-control-bg-hover, var(--xh-_field-variant-bg-hover));
+    --xh-field-bg-read-only: var(--xh-cascader-control-bg-readonly, var(--xh-_field-variant-bg-read-only));
+    --xh-field-bg-disabled: var(--xh-cascader-control-bg-disabled, var(--xh-_field-variant-bg-disabled));
+    --xh-field-fg-rest: var(--xh-cascader-control-fg, var(--xh-fg-default));
+    --xh-field-border-rest: var(--xh-cascader-control-border, var(--xh-_field-variant-border-rest));
+    --xh-field-border-hover: var(--xh-cascader-control-border-hover, var(--xh-_field-variant-border-hover));
+    --xh-field-border-focus: var(--xh-cascader-control-border-focus, var(--xh-_field-variant-border-focus));
+    --xh-field-border-invalid: var(--xh-cascader-control-border-invalid, var(--xh-_field-variant-border-invalid));
+    --xh-field-ring-focus: var(--xh-ring-focus);
+    --xh-field-ring-invalid: var(--xh-ring-invalid);
+    --xh-field-shadow-rest: var(--xh-cascader-control-shadow, none);
+    --xh-field-cursor-rest: pointer;
+    /* 家族 chrome 会重写 --xh-icon-size，使用者图标槽必须经桥接槽下发才能在盒内生效 */
+    --xh-field-glyph-size: var(--xh-cascader-icon-size, var(--xh-_field-size-glyph-size));
   }
 
   [data-scope='cascader'][data-part='control'][hidden] {
     display: none;
   }
 
-  /* hover 只在中性态换描边：invalid 正拿边框颜色说事，被 hover 盖掉那条信息就没了 */
-  [data-scope='cascader'][data-part='control']:hover:not([data-disabled], [data-invalid]) {
-    border-color: var(--xh-cascader-control-border-hover, var(--xh-_cascader-border-hover));
-  }
-
-  /* Tab 停靠点是盒里的 trigger（展开后才移进列里），环画在盒上 */
-  [data-scope='cascader'][data-part='control']:focus-within:not([data-disabled]) {
-    border-color: var(--xh-cascader-control-border-focus, var(--xh-_tone, var(--xh-border-control-focus)));
-    outline: var(--xh-ring-width) solid var(--xh-_cascader-ring);
-    outline-offset: var(--xh-ring-offset);
-  }
-
-  [data-scope='cascader'][data-part='control'][data-invalid] {
-    border-color: var(--xh-cascader-control-border-invalid, var(--xh-border-invalid));
-
-    /* 校验失败时环也跟着变红：两圈等宽相邻却一红一蓝，读的人不知道哪个才是当前状态 */
-    --xh-_cascader-ring: var(--xh-ring-invalid);
-  }
-
-  /* 只读仍可聚焦、浮层仍展得开、列仍能浏览，所以不置灰，只把底色压下去表示「改不动」 */
-  [data-scope='cascader'][data-part='control'][data-readonly] {
-    background: var(--xh-cascader-control-bg-readonly, var(--xh-bg-subtle));
-  }
-
-  [data-scope='cascader'][data-part='control'][data-disabled] {
-    background: var(--xh-cascader-control-bg-disabled, var(--xh-bg-subtle));
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
-  }
-
   /* 盒内那颗可聚焦的按钮：不画描边不铺底也不自带高度，只占满剩余宽度、排布回显与箭头 */
   [data-scope='cascader'][data-part='trigger'] {
     display: inline-flex;
@@ -197,7 +188,6 @@
   /* trigger 是单体控件，用原生 disabled（列里的集合条目一律 aria-disabled，写 :disabled 永不命中） */
   [data-scope='cascader'][data-part='trigger']:disabled {
     color: var(--xh-fg-disabled);
-    cursor: not-allowed;
   }
 
   /* 路径连起来会很长，必须能截断；框宽由盒定，这里得允许自己被压缩 */
@@ -219,8 +209,9 @@
   }
 
   /* 有值时清空钮顶上来，箭头让位：两个图标并排堆着，用户分不清点哪个。
-     让位而不是禁用——禁用的图标还占着位置，看着像坏了 */
-  [data-scope='cascader'][data-part='indicator'][data-clearable] {
+     判据查的是盒里此刻真有一颗没收起的清空钮，不是「有没有值」——
+     作者没摆清空钮时箭头照常留着，不然让了位没人接，指示符整个消失 */
+  [data-scope='cascader'][data-part='control']:has([data-part='clear-trigger']:not([hidden])) [data-part='indicator'] {
     display: none;
   }
 
@@ -230,7 +221,7 @@
     align-items: center;
     justify-content: center;
     color: var(--xh-cascader-indicator-fg, var(--xh-fg-muted));
-    transition: rotate var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+    transition: rotate var(--xh-motion-duration-micro) var(--xh-motion-ease-enter-strong);
   }
 
   [data-scope='cascader'][data-part='indicator'][hidden] {
@@ -257,63 +248,73 @@
     color: var(--xh-fg-disabled);
   }
 
-  /* 盒内靠右的小方钮，不撑高那一行 */
+  /* 盒内靠右的小方钮，不撑高那一行：正方视觉盒、inset 圆角、悬停 100 / 按下 200 与 0.97 按压、粗指针热区与
+     :focus-visible 关环（盒的 :focus-within 已画了一圈）全由 Action Control 的 field-inset ghost 档给，
+     组件只映射既有覆盖槽 */
   [data-scope='cascader'][data-part='clear-trigger'] {
-    display: inline-flex;
-    flex: none;
-    align-items: center;
-    justify-content: center;
-    inline-size: var(--xh-cascader-action-size, var(--xh-control-action-size));
-    block-size: var(--xh-cascader-action-size, var(--xh-control-action-size));
-    padding: 0;
-    border: 0;
-    border-radius: var(--xh-cascader-action-radius, var(--xh-shape-control));
-    background: var(--xh-cascader-action-bg, transparent);
-    color: var(--xh-cascader-action-fg, var(--xh-fg-muted));
-    font-family: inherit;
-    font-size: var(--xh-cascader-action-font-size, var(--xh-text-secondary-size));
-    line-height: var(--xh-leading-none);
-    cursor: pointer;
-    user-select: none;
-    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter), scale var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
-  }
-
+    --xh-action-visual-size: var(--xh-cascader-action-size, var(--xh-_action-profile-visual-size));
+    --xh-action-min-inline-size: var(--xh-cascader-action-size, var(--xh-_action-profile-visual-size));
+    --xh-action-radius: var(--xh-cascader-action-radius, var(--xh-shape-inset));
+    /* 底色阶梯由 ghost 档给（透明 → 100 → 200），使用者槽只作覆盖入口 */
+    --xh-action-bg-rest: var(--xh-cascader-action-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-cascader-action-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-cascader-action-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-cascader-action-fg, var(--xh-fg-muted));
+    --xh-action-fg-hover: var(--xh-cascader-action-fg-hover, var(--xh-fg-default));
+    --xh-action-border-rest: transparent;
+    --xh-action-highlight-rest: transparent;
+    --xh-action-shadow-rest: none;
+    --xh-action-shadow-hover: none;
+    --xh-action-shadow-pressed: none;
+    --xh-action-font-size: var(--xh-cascader-action-font-size, var(--xh-text-secondary-size));
+    /* 配方尚未把 profile 字形档灌进 --xh-icon-size，钮内字形先按 field-inset 档逐钮取值 */
+    --xh-icon-size: var(--xh-_action-profile-glyph-size);
+
+    border-width: 0;
+  }
+
+  /* 没值时连接层给的是 hidden 属性；家族那条 display 会把 UA 规则盖掉 */
   [data-scope='cascader'][data-part='clear-trigger'][hidden] {
     display: none;
   }
 
-  [data-scope='cascader'][data-part='clear-trigger']:hover {
-    background: var(--xh-cascader-action-bg-hover, var(--xh-bg-subtle-hover));
-    color: var(--xh-cascader-action-fg-hover, var(--xh-fg-default));
-  }
-
-  [data-scope='cascader'][data-part='clear-trigger']:active {
-    background: var(--xh-cascader-action-bg-active, var(--xh-bg-subtle-active));
-    scale: var(--xh-motion-scale-press);
-  }
-
-  /* 清空按钮退出了 Tab 序列（tabindex=-1），正常操作走不到这里；
-     留着是给程序化聚焦兜底，落焦时得看得见 */
-  [data-scope='cascader'][data-part='clear-trigger']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
-  }
-
   /* 级联的骨架就在这一条上：列沿书写方向并排，一层一列。
      横向随列数增减，因此不设固定宽度，只给每列自己的宽度 */
   [data-scope='cascader'][data-part='content'] {
+    position: relative;
     display: flex;
     flex-direction: row;
     align-items: stretch;
-    max-inline-size: var(--xh-cascader-content-max-w, var(--xh-overlay-max-w-xl));
-    border: var(--xh-stroke-thin) solid var(--xh-cascader-content-border, var(--xh-border-default));
-    border-radius: var(--xh-cascader-content-radius, var(--xh-shape-surface));
-    background: var(--xh-cascader-content-bg, var(--xh-bg-surface));
-    color: var(--xh-cascader-content-fg, var(--xh-fg-default));
-    box-shadow: var(--xh-cascader-content-shadow, var(--xh-elevation-floating));
+    /* 静态档与落位后的可用宽度取小：列多起来时外框自己就宽过了可用区，
+       盒内不产生溢出，下面那条 overflow-x 便一直没事可做，最右那一列落在屏外点不到 */
+    max-inline-size: min(var(--xh-cascader-content-max-w, var(--xh-overlay-max-w-xl)), var(--xh-_cascader-available-w));
+    border: var(--xh-stroke-thin) solid var(--xh-cascader-content-border, var(--xh-material-frosted-border));
+    border-radius: var(--xh-cascader-content-radius, var(--xh-shape-overlay));
+    background: var(--xh-cascader-content-bg, var(--xh-material-frosted-bg));
+    color: var(--xh-cascader-content-fg, var(--xh-material-frosted-fg));
+    box-shadow: var(--xh-cascader-content-shadow, var(--xh-material-frosted-shadow));
+    -webkit-backdrop-filter: var(--xh-cascader-content-backdrop, var(--xh-material-frosted-backdrop));
+    backdrop-filter: var(--xh-cascader-content-backdrop, var(--xh-material-frosted-backdrop));
     /* 列多到放不下时整体横向滚动；纵向溢出归每一列自己 */
     overflow-x: auto;
+    /* 浮层滚动面：滚到头不把页面一起带走 */
+    overscroll-behavior: contain;
     pointer-events: auto;
+    /* 各列与搜索列表的竖条贴在自己的盒子上、挂在这一层里（它已是定位盒）：轨道不画底，
+       条子随列一起横滚，列与列之间才不会各多出一道灰带 */
+    --xh-scrollbar-track-bg: transparent;
+  }
+
+  /* 唯一外壳的内侧顶光；列和状态部件不另画材质面。 */
+  [data-scope='cascader'][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-cascader-content-highlight, var(--xh-material-frosted-highlight));
+    pointer-events: none;
   }
 
   /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
@@ -328,13 +329,15 @@
   }
 
   [data-scope='cascader'][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='cascader'][data-part='content'][data-state='closed'] {
-    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+    animation: xh-overlay-slide-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   /* 一列：宽度由内容撑出、设下限防塌，高度定死——切换展开路径时浮层不上下跳动，
@@ -349,6 +352,8 @@
     padding-block: var(--xh-cascader-column-py, var(--xh-space-1));
     padding-inline: var(--xh-cascader-column-px, var(--xh-space-1));
     overflow-y: auto;
+    /* 浮层滚动面：滚到头不把页面一起带走 */
+    overscroll-behavior: contain;
   }
 
   /* 展开路径砍短了这一列就收起来。display 盖掉了 UA 的 [hidden]{display:none}，
@@ -358,40 +363,100 @@
   }
 
   /* 分隔线画在列的起始缘，且第一列不画：这样列数增减时线永远只出现在列与列之间。
-     用逻辑属性，rtl 下自动跑到另一侧 */
-  [data-scope='cascader'][data-part='column'] + [data-scope='cascader'][data-part='column'] {
-    border-inline-start: var(--xh-stroke-thin) solid var(--xh-cascader-column-divider, var(--xh-border-subtle));
-  }
-
-  /* 焦点落在根列上只有一种情形：指针打开、无选中值、还没有任何条目当锚点。
-     那一刻它认领着 Tab 位，环画在列内沿；有锚点时环长在条目上，列不再画 */
-  [data-scope='cascader'][data-part='column'][tabindex='0']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: calc(-1 * var(--xh-ring-width));
+     用逻辑属性，rtl 下自动跑到另一侧。每列后面紧跟着它自己的竖条节点，相邻选择器接不到下一列，
+     按「前面有过列」取后续的列 */
+  [data-scope='cascader'][data-part='column'] ~ [data-scope='cascader'][data-part='column'] {
+    border-inline-start: var(--xh-stroke-thin) solid var(--xh-cascader-column-divider, var(--xh-material-frosted-separator));
   }
 
   [data-scope='cascader'][data-part='column']:not([tabindex='0']):focus-visible {
     outline: none;
   }
 
-  [data-scope='cascader'][data-part='item'] {
+  [data-scope='cascader'][data-part='group'] {
     display: flex;
-    align-items: center;
-    gap: var(--xh-cascader-row-gap, var(--xh-_cascader-gap));
-    max-inline-size: var(--xh-cascader-row-max-w, var(--xh-overlay-max-w));
-    padding-block: var(--xh-cascader-row-py, var(--xh-_cascader-row-py));
-    padding-inline: var(--xh-cascader-row-px, var(--xh-_cascader-row-px));
-    border-radius: var(--xh-cascader-row-radius, var(--xh-shape-control));
-    color: var(--xh-cascader-row-fg, var(--xh-fg-default));
-    font-size: var(--xh-cascader-row-font-size, var(--xh-_cascader-font-size));
+    flex: none;
+    flex-direction: column;
+    gap: var(--xh-cascader-group-gap, var(--xh-list-option-gap));
+  }
+
+  [data-scope='cascader'][data-part='group'][hidden] {
+    display: none;
+  }
+
+  /* 组间留白只加在后继分组上：首组顶上已经有列的内边距，再加一层会显得头重 */
+  [data-scope='cascader'][data-part='group'] + [data-scope='cascader'][data-part='group'] {
+    margin-block-start: var(--xh-cascader-group-spacing, var(--xh-space-1_5));
+  }
+
+  /* 分组标题不是条目、进不了导航，画成小号次要文字，
+     内缩与条目对齐（同一个 padding-inline），标题与条目文字才在一条竖线上 */
+  [data-scope='cascader'][data-part='group-label'] {
+    display: block;
+    padding-block: var(--xh-cascader-group-label-py, var(--xh-space-1));
+    padding-inline: var(--xh-cascader-group-label-px, var(--xh-_cascader-row-px));
+    color: var(--xh-cascader-group-label-fg, var(--xh-material-frosted-fg-muted));
+    font-size: var(--xh-cascader-group-label-font-size, var(--xh-text-caption-size));
+    font-weight: var(--xh-cascader-group-label-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+    user-select: none;
+  }
+
+  [data-scope='cascader'][data-part='group-label'][hidden] {
+    display: none;
+  }
+
+  [data-scope='cascader'][data-part='group-label'][data-disabled] {
+    color: var(--xh-fg-disabled);
+  }
+
+  /* 列内条目：网格、尺寸档、悬停 / 高亮 100、按下 200、展开路径的中性面（与悬停同档）、禁用面与选中标记
+     由 Collection Item 家族按 overlay 语境给（选中 = 透明底 + 行尾对号，正文保持 rest 色与常规字重），
+     公开 Cascader 槽只映射到家族合同。data-highlighted 跟的是连接层记的焦点行（指针与键盘共用），
+     环只在真正的键盘焦点上接回，见下 */
+  [data-scope='cascader'][data-part='item'] {
+    --xh-collection-block-padding: var(--xh-cascader-item-py, var(--xh-_cascader-row-py));
+    --xh-collection-inline-padding: var(--xh-cascader-item-px, var(--xh-_cascader-row-px));
+    --xh-collection-gap: var(--xh-cascader-item-gap, var(--xh-_cascader-gap));
+    --xh-collection-font-size: var(--xh-cascader-item-font-size, var(--xh-_cascader-font-size));
+    --xh-collection-radius: var(--xh-cascader-item-radius, var(--xh-shape-control));
+    --xh-collection-glyph-size: var(--xh-cascader-icon-size, var(--xh-_collection-glyph-size));
+    --xh-collection-fg-rest: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-hover: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-keyboard-highlight: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-open-path: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-selected: var(--xh-cascader-item-fg-selected, var(--xh-cascader-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-selected-highlight: var(--xh-cascader-item-fg-selected, var(--xh-cascader-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-selected-hover: var(--xh-cascader-item-fg-selected, var(--xh-cascader-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-selected-pressed: var(--xh-cascader-item-fg-selected, var(--xh-cascader-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-pressed: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-font-weight-open-path: var(--xh-cascader-item-active-font-weight, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected: var(--xh-cascader-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected-highlight: var(--xh-cascader-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected-hover: var(--xh-cascader-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected-pressed: var(--xh-cascader-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-bg-hover: var(--xh-cascader-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-keyboard-highlight: var(--xh-cascader-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-open-path: var(--xh-cascader-item-bg-active, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-highlight: var(--xh-cascader-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-hover: var(--xh-cascader-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-pressed: var(--xh-cascader-item-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-bg-selected-pressed: var(--xh-cascader-item-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-outline-keyboard-highlight: transparent;
+    --xh-collection-outline-selected-highlight: transparent;
+    --xh-collection-indicator-fg-rest: var(--xh-cascader-item-check-fg, var(--xh-cascader-item-indicator-fg, var(--xh-_cascader-accent)));
+    --xh-collection-indicator-fg-checked: var(--xh-cascader-item-check-fg, var(--xh-cascader-item-indicator-fg, var(--xh-_cascader-accent)));
+    --xh-collection-indicator-fg-selected: var(--xh-cascader-item-check-fg, var(--xh-cascader-item-indicator-fg, var(--xh-_cascader-accent)));
+    --xh-collection-indicator-fg-selected-hover: var(--xh-cascader-item-check-fg, var(--xh-cascader-item-indicator-fg, var(--xh-_cascader-accent)));
+    --xh-collection-indicator-fg-selected-highlight: var(--xh-cascader-item-check-fg, var(--xh-cascader-item-indicator-fg, var(--xh-_cascader-accent)));
+    --xh-collection-indicator-fg-selected-pressed: var(--xh-cascader-item-check-fg, var(--xh-cascader-item-indicator-fg, var(--xh-_cascader-accent)));
+    --xh-collection-indicator-fg-open-path: var(--xh-cascader-item-check-fg, var(--xh-cascader-item-indicator-fg, var(--xh-_cascader-accent)));
+
+    max-inline-size: var(--xh-cascader-item-max-w, var(--xh-overlay-max-w));
     /* 行高留出文字的上下伸展空间，行内那层 overflow:hidden 才不会把字削掉 */
-    line-height: var(--xh-cascader-row-leading, var(--xh-leading-normal));
+    line-height: var(--xh-cascader-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);
   }
 
   /* 条目常挂不卸载：不属于当前这一列的那些靠 hidden 收起。
@@ -400,80 +465,97 @@
     display: none;
   }
 
-  /* 底色分两档、靠色相分家：悬停与键盘锚点是中性灰轻档，展开路径是品牌淡底加粗。
-     hover 恒中性灰、不接语气槽——两档同色相的话路径就认不出来了。
-     悬停展开把路径挪走后留在原地的锚点降回轻档，每列至多一条路径高亮 */
-  [data-scope='cascader'][data-part='item']:not([data-disabled]):is(:hover, [data-highlighted]) {
-    background: var(--xh-cascader-row-bg-hover, var(--xh-bg-subtle));
+  /* 一列开幕：条目自上而下逐条淡入。列从 hidden 转回来、或换了展开路径把另一批条目放出来时，
+     这段动画重新起跑。backwards 让每条在自己那份延迟里保持起始帧 */
+  [data-scope='cascader'][data-part='column'] [data-part='item'] {
+    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter) backwards;
   }
 
-  /* 必须排在轻档之后：锚点走到路径上时同特指度靠书写顺序压过轻档 */
-  [data-scope='cascader'][data-part='item']:not([data-disabled])[data-in-path] {
-    background: var(--xh-cascader-row-bg-active, var(--xh-_cascader-active-bg));
-    font-weight: var(--xh-cascader-row-active-font-weight, var(--xh-font-weight-semibold));
+  /* 交错的间隔：第二条起逐级往后推，第六条起统一钉在第五级，条目再多也不会拖出一条越来越慢的尾巴。
+     列里同时挂着别的父节点下的条目（收起态），计数把它们排掉，序号才对得上看得见的那几条 */
+  [data-scope='cascader'][data-part='column'] [data-part='item']:nth-child(2 of :not([hidden])) {
+    animation-delay: var(--xh-motion-stagger-step);
   }
 
-  /* 选中只换文字色与字重，配合行尾的 ✓ 标记；底色强档归展开路径、轻档归悬停，
-     三者因此能同时看见 */
-  [data-scope='cascader']:is([data-part='item'], [data-part='search-item'])[data-state='checked'] {
-    color: var(--xh-cascader-row-fg-selected, var(--xh-_cascader-selected-fg));
-    font-weight: var(--xh-cascader-row-selected-font-weight, var(--xh-font-weight-medium));
+  [data-scope='cascader'][data-part='column'] [data-part='item']:nth-child(3 of :not([hidden])) {
+    animation-delay: calc(2 * var(--xh-motion-stagger-step));
   }
 
-  /* 条目自己就是 option，环直接画在它身上；往内收，行是撑满列宽的，环画在外沿会被裁掉 */
-  [data-scope='cascader'][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='cascader'][data-part='column'] [data-part='item']:nth-child(4 of :not([hidden])) {
+    animation-delay: calc(3 * var(--xh-motion-stagger-step));
   }
 
-  /* 禁用走 aria-disabled 而非原生 disabled：条目仍要可聚焦（它还得当方向键的起点），
-     所以只能靠 data-disabled 表达，写 :disabled 永远不命中 */
-  [data-scope='cascader'][data-part='item'][data-disabled] {
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
+  [data-scope='cascader'][data-part='column'] [data-part='item']:nth-child(5 of :not([hidden])) {
+    animation-delay: calc(4 * var(--xh-motion-stagger-step));
+  }
+
+  [data-scope='cascader'][data-part='column'] [data-part='item']:nth-child(n + 6 of :not([hidden])) {
+    animation-delay: calc(5 * var(--xh-motion-stagger-step));
+  }
+
+  /* 键盘焦点出现时环才接回并立即到位，不压在背景过渡的中间帧上 */
+  [data-scope='cascader'][data-part='item']:focus-visible:not(:hover) {
+    --xh-collection-outline-keyboard-highlight: var(--xh-ring-focus);
+    --xh-collection-outline-selected-highlight: var(--xh-ring-focus);
+
+    transition: none;
   }
 
-  /* 分支条目行尾画右向小箭头：不点开也看得出还有下一级。位置由 item-text 的 flex:1 顶到行尾。
+  /* 分支条目行尾画右向小箭头：不点开也看得出还有下一级。落在家族网格的 suffix 列、跨两行居中。
      与菜单族的子菜单箭头同走字形令牌——此前这里是「描全边框再抹掉两条、把剩下的直角旋 45 度」，
-     作者换掉标记时换不动它，RTL 还得再翻一次旋转角 */
+     作者换掉标记时换不动它，RTL 还得再翻一次旋转角。
+     箭头是指示符（§6.5）：与同一行的标记盒同走 --xh-control-indicator-size，不读家族按档下发的
+     --xh-icon-size——按图标档取的 20px 会比 16px 的标记盒大一圈 */
   [data-scope='cascader'][data-part='item'][data-branch]::after {
     content: '';
-    flex: none;
-    inline-size: var(--xh-cascader-branch-arrow-size, var(--xh-icon-size, var(--xh-glyph-size-text)));
-    block-size: var(--xh-cascader-branch-arrow-size, var(--xh-icon-size, var(--xh-glyph-size-text)));
+    grid-column: suffix;
+    grid-row: 1 / span 2;
+    inline-size: var(--xh-cascader-branch-arrow-size, var(--xh-control-indicator-size));
+    block-size: var(--xh-cascader-branch-arrow-size, var(--xh-control-indicator-size));
+    margin-inline-start: var(--xh-cascader-item-gap, var(--xh-_cascader-gap));
     background-color: var(--xh-cascader-branch-arrow-fg, var(--xh-fg-subtle));
     -webkit-mask: var(--xh-glyph-mark-chevron-right) center / contain no-repeat;
     mask: var(--xh-glyph-mark-chevron-right) center / contain no-repeat;
   }
 
   [data-scope='cascader'][data-part='item'][data-branch][data-disabled]::after {
-    border-color: var(--xh-fg-disabled);
+    background-color: var(--xh-fg-disabled);
+  }
+
+  [data-scope='cascader'][data-part='item'][data-branch]:dir(rtl)::after {
+    -webkit-mask-image: var(--xh-glyph-mark-chevron-left);
+    mask-image: var(--xh-glyph-mark-chevron-left);
   }
 
+  /* 正文落在家族网格的 text 列；网格项默认最小尺寸是内容尺寸，不归零则长文本把行撑破、省略号轮不上 */
   [data-scope='cascader'][data-part='item-text'] {
-    flex: 1;
     min-inline-size: 0;
     overflow: hidden;
     white-space: nowrap;
     text-overflow: ellipsis;
   }
 
-  /* 勾选标记只在选中项上出现；未选中时占位不塌，切换选中不引起行宽抖动 */
+  /* 勾选标记落在家族网格的 indicator 列，只在选中项上显形（家族按 aria-selected / data-state=checked 给）；
+     未选中时占位不塌，切换选中不引起行宽抖动。
+     盒里的勾与半选杠是指示符（§6.5）：盒在自己身上把 --xh-icon-size 改接到盒的尺，皮肤画的兜底字形与作者
+     塞进盒里的 XhIcon 读同一把尺、与盒同边长（行尾标记不是勾选格，不取 × 0.75，与搜索候选行尾的勾同尺）；
+     不读家族按档下发到行的 --xh-icon-size——那支只管作者放进条目里的图标，按图标档取的 20px 会比 16 / 14 的盒还大 */
   [data-scope='cascader'][data-part='item-indicator'] {
+    --xh-icon-size: var(--xh-cascader-item-indicator-size, var(--xh-control-indicator-size));
+
     display: inline-flex;
-    flex: none;
     align-items: center;
     justify-content: center;
     inline-size: var(--xh-cascader-item-indicator-size, var(--xh-control-indicator-size));
-    color: var(--xh-cascader-item-indicator-fg, var(--xh-_tone, var(--xh-fg-brand)));
-    visibility: hidden;
+    block-size: var(--xh-cascader-item-indicator-size, var(--xh-control-indicator-size));
   }
 
   [data-scope='cascader'][data-part='item-indicator'][hidden] {
     display: none;
   }
 
-  /* 没写内容就由皮肤画勾；作者往部件里塞了自己的图形，这条规则即不命中 */
+  /* 没写内容就由皮肤画勾；作者往部件里塞了自己的图形，这条规则即不命中。
+     尺寸读标记盒自己改接过的 --xh-icon-size：与盒同边长，随指示符档换档（见上面标记盒那块） */
   [data-scope='cascader'][data-part='item-indicator']:empty::before {
     content: '';
     display: inline-block;
@@ -485,10 +567,6 @@
     mask: var(--xh-glyph-mark-check) center / contain no-repeat;
   }
 
-  [data-scope='cascader'][data-part='item-indicator'][data-state='checked'] {
-    visibility: visible;
-  }
-
   /* 级联勾选的半选态只在皮肤自绘（:empty）时露面画横杠：
      作者塞了自己的选中图形时，半选放出来会顶着一个语义相反的勾，表达交还作者 */
   [data-scope='cascader'][data-part='item-indicator'][data-state='indeterminate']:empty {
@@ -504,9 +582,9 @@
     background-color: currentColor;
     -webkit-mask: var(--xh-glyph-mark-minus) center / contain no-repeat;
     mask: var(--xh-glyph-mark-minus) center / contain no-repeat;
-    font-weight: var(--xh-font-weight-semibold);
   }
 
+  /* 家族按行的禁用降级标记色；半选横线也一并跟着 */
   [data-scope='cascader'][data-part='item-indicator'][data-disabled] {
     color: var(--xh-fg-disabled);
   }
@@ -522,7 +600,7 @@
     padding-block: var(--xh-cascader-input-py, var(--xh-space-2));
     padding-inline: var(--xh-cascader-input-px, var(--xh-control-px-md));
     border: none;
-    border-block-end: var(--xh-stroke-thin) solid var(--xh-cascader-search-divider, var(--xh-border-subtle));
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-cascader-search-divider, var(--xh-material-frosted-separator));
     border-start-start-radius: inherit;
     border-start-end-radius: inherit;
     background: none;
@@ -532,14 +610,26 @@
     line-height: var(--xh-leading-normal);
   }
 
-  [data-scope='cascader'][data-part='input']:focus-visible {
-    outline: none;
-  }
-
   [data-scope='cascader'][data-part='input'][hidden] {
     display: none;
   }
 
+  /* 自动填充：引擎给填过的框强加一套系统色（多数是黄底黑字），盖得过 background 与 color，
+     深色档下就剩一条不跟主题走的黄带。底改用 inset 阴影铺回来，扩散量 100vmax 填满内容盒；
+     字改用 -webkit-text-fill-color 接回来，那是这个态下唯一还听样式表的前景通道。
+     不去拉长 transition 把系统底推迟显现：那只是把它藏起来，减弱动效通道一关过渡就当场露出。
+     两个选择器名分写两条：一条选择器列表里只要有一个名字不被认识，整条规则就被丢弃。
+     搜索框排在浮层面里，铺的底取浮起面而不是页面底，不然框内会比周围亮出一块。 */
+  [data-scope='cascader'][data-part='input']:autofill {
+    box-shadow: inset 0 0 0 100vmax var(--xh-cascader-input-autofill-bg, var(--xh-bg-surface));
+    -webkit-text-fill-color: var(--xh-cascader-input-autofill-fg, var(--xh-fg-default));
+  }
+
+  [data-scope='cascader'][data-part='input']:-webkit-autofill {
+    box-shadow: inset 0 0 0 100vmax var(--xh-cascader-input-autofill-bg, var(--xh-bg-surface));
+    -webkit-text-fill-color: var(--xh-cascader-input-autofill-fg, var(--xh-fg-default));
+  }
+
   /* 与列同高：搜索视图与浏览视图互换时浮层不改高度，候选多了在列表内自己滚 */
   [data-scope='cascader'][data-part='search-list'] {
     display: flex;
@@ -549,6 +639,8 @@
     block-size: var(--xh-cascader-column-h, var(--xh-viewport-h-sm));
     padding: var(--xh-cascader-search-p, var(--xh-space-1));
     overflow-y: auto;
+    /* 浮层滚动面：滚到头不把页面一起带走 */
+    overscroll-behavior: contain;
   }
 
   [data-scope='cascader'][data-part='search-list'][hidden] {
@@ -565,35 +657,86 @@
     display: none;
   }
 
-  /* 候选与列内条目同一套行度量，虚拟高亮与悬停同用轻档 */
+  /* 候选与列内条目同一套行度量与家族状态面（悬停 / 高亮 100、按下 200、禁用面由 Collection Item 给）。
+     搜索结果没有独立的正文部件，匿名文本进不了家族网格的 text 列，行保持块级排版，
+     末端为同一枚皮肤对号预留固定轨 */
   [data-scope='cascader'][data-part='search-item'] {
-    padding-block: var(--xh-cascader-row-py, var(--xh-_cascader-row-py));
-    padding-inline: var(--xh-cascader-row-px, var(--xh-_cascader-row-px));
+    --xh-collection-block-padding: var(--xh-cascader-item-py, var(--xh-_cascader-row-py));
+    --xh-collection-inline-padding: var(--xh-cascader-item-px, var(--xh-_cascader-row-px));
+    --xh-collection-gap: var(--xh-cascader-item-gap, var(--xh-_cascader-gap));
+    --xh-collection-font-size: var(--xh-cascader-item-font-size, var(--xh-_cascader-font-size));
+    --xh-collection-radius: var(--xh-cascader-item-radius, var(--xh-shape-control));
+    --xh-collection-fg-rest: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-hover: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-keyboard-highlight: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-selected: var(--xh-cascader-item-fg-selected, var(--xh-cascader-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-selected-highlight: var(--xh-cascader-item-fg-selected, var(--xh-cascader-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-selected-hover: var(--xh-cascader-item-fg-selected, var(--xh-cascader-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-selected-pressed: var(--xh-cascader-item-fg-selected, var(--xh-cascader-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-pressed: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-font-weight-selected: var(--xh-cascader-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected-highlight: var(--xh-cascader-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected-hover: var(--xh-cascader-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected-pressed: var(--xh-cascader-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-bg-hover: var(--xh-cascader-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-keyboard-highlight: var(--xh-cascader-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-highlight: var(--xh-cascader-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-hover: var(--xh-cascader-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-pressed: var(--xh-cascader-item-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-bg-selected-pressed: var(--xh-cascader-item-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-outline-keyboard-highlight: transparent;
+    --xh-collection-outline-selected-highlight: transparent;
+
+    position: relative;
+    display: block;
+    /* 末端为对号预留固定轨：对号绝对定位，不进内容流 */
+    padding-inline-end: calc(
+      var(--xh-cascader-item-px, var(--xh-_cascader-row-px)) +
+        var(--xh-cascader-item-indicator-size, var(--xh-control-indicator-size)) +
+        var(--xh-cascader-item-gap, var(--xh-_cascader-gap))
+    );
     overflow: hidden;
-    border-radius: var(--xh-cascader-row-radius, var(--xh-shape-control));
-    color: var(--xh-cascader-row-fg, var(--xh-fg-default));
-    font-size: var(--xh-cascader-row-font-size, var(--xh-_cascader-font-size));
-    line-height: var(--xh-cascader-row-leading, var(--xh-leading-normal));
+    line-height: var(--xh-cascader-item-leading, var(--xh-leading-normal));
     text-overflow: ellipsis;
     white-space: nowrap;
-    cursor: pointer;
     user-select: none;
-    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
-  [data-scope='cascader'][data-part='search-item']:not([data-disabled]):is(:hover, [data-highlighted]) {
-    background: var(--xh-cascader-row-bg-hover, var(--xh-bg-subtle));
+  /* 键盘焦点出现时环才接回并立即到位，不压在背景过渡的中间帧上 */
+  [data-scope='cascader'][data-part='search-item']:focus-visible:not(:hover) {
+    --xh-collection-outline-keyboard-highlight: var(--xh-ring-focus);
+    --xh-collection-outline-selected-highlight: var(--xh-ring-focus);
+
+    transition: none;
+  }
+
+  /* 自动生成的搜索结果复用 item-indicator 的尺寸、颜色和对号字形，不新增第二套作者槽。 */
+  [data-scope='cascader'][data-part='search-item']::after {
+    content: '';
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-end: var(--xh-cascader-item-px, var(--xh-_cascader-row-px));
+    inline-size: var(--xh-cascader-item-indicator-size, var(--xh-control-indicator-size));
+    block-size: var(--xh-cascader-item-indicator-size, var(--xh-control-indicator-size));
+    translate: 0 -50%;
+    background-color: var(--xh-cascader-item-indicator-fg, var(--xh-_cascader-accent));
+    visibility: hidden;
+    -webkit-mask: var(--xh-glyph-mark-check) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-check) center / contain no-repeat;
   }
 
-  /* 焦点恒在输入框，环只跟虚拟高亮走，悬停不画；往内收，行是撑满列宽的，环画在外沿会被裁掉 */
-  [data-scope='cascader'][data-part='search-item']:not([data-disabled])[data-highlighted] {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: calc(-1 * var(--xh-ring-width));
+  [data-scope='cascader'][data-part='search-item'][data-state='checked']::after {
+    visibility: visible;
   }
 
-  [data-scope='cascader'][data-part='search-item'][data-disabled] {
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
+  [data-scope='cascader'][data-part='search-item'][data-state='indeterminate']::after {
+    visibility: visible;
+    -webkit-mask-image: var(--xh-glyph-mark-minus);
+    mask-image: var(--xh-glyph-mark-minus);
+  }
+
+  [data-scope='cascader'][data-part='search-item'][data-disabled]::after {
+    background-color: var(--xh-fg-disabled);
   }
 
   [data-scope='cascader'][data-part='search-item'][hidden] {
@@ -614,14 +757,56 @@
     min-inline-size: var(--xh-cascader-column-min-w, 7rem);
     min-block-size: var(--xh-cascader-empty-min-h, 5rem);
     padding: var(--xh-cascader-empty-p, var(--xh-space-3));
-    color: var(--xh-cascader-empty-fg, var(--xh-fg-subtle));
-    font-size: var(--xh-cascader-row-font-size, var(--xh-_cascader-font-size));
+    color: var(--xh-cascader-empty-fg, var(--xh-material-frosted-fg-muted));
+    font-size: var(--xh-cascader-item-font-size, var(--xh-_cascader-font-size));
   }
 
   [data-scope='cascader'][data-part='empty'][hidden] {
     display: none;
   }
 
+  /* 在途占位：与空态占位同一个位置、同一副观感，两者不同屏 */
+  [data-scope='cascader'][data-part='loading'] {
+    display: flex;
+    flex: 0 0 100%;
+    align-items: center;
+    justify-content: center;
+    min-inline-size: var(--xh-cascader-loading-min-w, var(--xh-cascader-column-min-w, 7rem));
+    min-block-size: var(--xh-cascader-loading-min-h, 5rem);
+    padding: var(--xh-cascader-loading-p, var(--xh-space-3));
+    color: var(--xh-cascader-loading-fg, var(--xh-material-frosted-fg-muted));
+    font-size: var(--xh-cascader-loading-font-size, var(--xh-_cascader-font-size));
+  }
+
+  [data-scope='cascader'][data-part='loading'][hidden] {
+    display: none;
+  }
+
+  /* 底栏在场时浮层壳允许换行：列照旧并排在第一行，底栏占满一整行落在列下面。
+     没写底栏的浮层不命中这条，列多到放不下时仍是整体横向滚动 */
+  [data-scope='cascader'][data-part='content']:has(> [data-part='footer']) {
+    flex-wrap: wrap;
+  }
+
+  /* 浮层底部的操作区：横跨全部列，与列之间用一条分隔线断开 */
+  [data-scope='cascader'][data-part='footer'] {
+    display: flex;
+    /* 基准就是一整行：换行容器里它因此自己独占一行，落在全部列的下面 */
+    flex-basis: 100%;
+    align-items: center;
+    gap: var(--xh-cascader-footer-gap, var(--xh-space-2));
+    padding-block: var(--xh-cascader-footer-py, var(--xh-space-2));
+    padding-inline: var(--xh-cascader-footer-px, var(--xh-space-2));
+    border-block-start: var(--xh-stroke-thin) solid var(--xh-cascader-footer-border, var(--xh-border-subtle));
+    color: var(--xh-cascader-footer-fg, var(--xh-fg-muted));
+    font-size: var(--xh-cascader-footer-font-size, var(--xh-text-secondary-size));
+  }
+
+  /* 上面给了 display，UA 的 [hidden]{display:none} 已被盖掉，这里补回来 */
+  [data-scope='cascader'][data-part='footer'][hidden] {
+    display: none;
+  }
+
   /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
   [data-scope='cascader'][data-part='clear-trigger']:empty::before {
     content: '';
@@ -633,32 +818,30 @@
     -webkit-mask: var(--xh-glyph-mark-close) center / contain no-repeat;
     mask: var(--xh-glyph-mark-close) center / contain no-repeat;
   }
-}
 
-@layer xihan.motion {
-  /* 浮层是横向长出来的：淡入之外再沿书写方向起始缘推一小段，观感上像列被「拉开」。
-     位移量从 content 上的私有槽取，rtl 侧翻符号后同一份关键帧两个方向都对。
-     关键帧写在本文件里、名字带组件前缀，不动公共的那一份 */
-  @keyframes xh-pop-in {
-    from {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
+  @media (forced-colors: active) {
+    /* 蒙版底色会被系统改成 Canvas 而消失；明确用系统前景保住箭头、对号与半选横线。 */
+    [data-scope='cascader'][data-part='item'][data-branch]::after,
+    [data-scope='cascader'][data-part='item-indicator']:empty::before,
+    [data-scope='cascader'][data-part='search-item']::after {
+      forced-color-adjust: none;
+      background-color: CanvasText;
     }
 
-    to {
-      opacity: 1;
-      scale: 1;
+    [data-scope='cascader'][data-part='item'][data-branch][data-disabled]::after,
+    [data-scope='cascader'][data-part='item-indicator'][data-disabled]:empty::before,
+    [data-scope='cascader'][data-part='search-item'][data-disabled]::after {
+      background-color: GrayText;
     }
   }
-  @keyframes xh-pop-out {
-    from {
-      opacity: 1;
-      scale: 1;
-    }
+}
 
-    to {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
+@layer xihan.motion {
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    [data-scope='cascader'][data-part='positioner'] {
+      display: none;
     }
   }
 }