@manohub/ui 0.7.0 → 0.7.1

package/dist/styles/components/form.css

@@ -13,7 +13,13 @@
    （farris 用绝对定位的浮层提示条，在弹窗里会压住下一行控件）。
 
    label 列宽只由变量驱动：Form / Form.Item 落 `--mh-form-label-width`，默认取令牌，
-   故换宽窄不需要在消费方写 CSS。 */
+   故换宽窄不需要在消费方写 CSS。
+
+   行几何是**两列 grid**（label 列 + 控件列）：label 与控件同处第 1 行、交叉轴居中 ⇒ 两侧文字
+   落在同一条中线上；错误 / 说明是**行的直接子节点**，自然落第 2 行起，不会把 label 带走。
+   对齐**不依赖任何「控件高度」常量**（从前那个 `--ui-form-control-height` 在骨架层没有出处，
+   回退 `auto` ⇒ label 盒退化成一行文字并贴行顶，档位越高错得越多）。
+   需要顶对齐的行（文本域自动判定、或消费方显式 `align`）见下面的「行内垂直对齐档」。 */
 
 /* 行距取 8px 档：Form.Item 自己已经是一个完整行（label 与控件等高 + 错误/说明按文档流往下排），
    再用 16px 行距会把表单拉得很散 —— 尤其是步骤⑤那种「只读文本行」的摘要，行与行之间会显得发虚。
@@ -23,27 +29,83 @@
   display: flex;
   flex-direction: column;
   gap: var(--ui-space-2);
+  /* 多列公式用的三个变量（**都在本件**，不进 theme 令牌文件）：
+     - `--mh-form-columns`：数字档的**列数上限**（档位类只覆盖它，不复制几何）；
+     - `--mh-form-column-min`：一列的**最小宽度**（`columnMinWidth` 行内覆盖，缺省取令牌 320）；
+     - `--mh-form-gap`：行距 —— 公式里必须用**与实体 gap 同一个值**算轨道下限
+       （从前这里硬编码 8px，`gap` 调大后列宽会算偏、临界宽度上还会误判是否回落）。 */
+  --mh-form-columns: 2;
+  --mh-form-column-min: var(--ui-form-column-min);
+  --mh-form-gap: var(--ui-space-2);
 }
 
-/* 两列（Form columns=2）：`auto-fit` + 列最小宽度 ⇒ 容器够宽才并排、窄了**自动回落一列**
-   （不需要媒体查询，也不需要容器查询）。`align-items: start` 让同一行的两个字段各自顶部对齐，
-   不被隔壁那个「错误 + 多行说明」撑高的格子拉扯。 */
-
-.mh-form--two-column {
+/* ===== 多列（数字档：`columns` = 2 / 3 / 4）=====
+ * 轨道下限取「**最小列宽**」与「**按 N 列等分**」的较大者，配 `auto-fit`：
+ * - 容器放得下 N 列 ⇒ 排 N 列；
+ * - 放不下 ⇒ 轨道数减少（**自动回落**，不会把控件压成窄条）。
+ *
+ * 把「均分值」当轨道下限就是「**上限 N 列**」的实现 —— 没有它，`auto-fit` 会一路排下去
+ * （实测 1400px 得 4 列，与「最多 N 列」的承诺不符）。
+ *
+ * 这条是表单与 `Layout.Row` 的**关键差别**：后者列数恒定、窄了等分收窄（实测 480px 容器里
+ * Form 回落成一列、控件还有 360px；恒定两列会把控件压到 ~104px）。表单会被放进抽屉 / 弹窗 /
+ * 分栏，容器宽度不可预知，所以要的是「回落到能用」而不是「列数不变」。
+ *
+ * `align-items: start`：同一行的字段各自顶部对齐，不被隔壁那个「错误 + 多行说明」撑高的格子拉扯。
+ *
+ * `mh-form--two-column` 是 `columns={2}` 的**历史类名**（已发布过，改名属破坏性变更），
+ * 与 3~6 档共用下面这份几何声明（`2` 与 `3+` 走两个类名只是历史包袱，样式上完全等价）。 */
+
+.mh-form--two-column,
+.mh-form--columns-3,
+.mh-form--columns-4,
+.mh-form--columns-5,
+.mh-form--columns-6 {
   display: grid;
-  /* 上限 2 列 + 最小列宽：track 下限取「最小列宽」与「按 2 列等分」的较大者
-     —— 否则宽表单里 auto-fit 会一路排到 4 列（实测 1400px 得 4 列），
-     而 `columns={2}` 承诺的是"最多 2 列、窄了回落"（与 Layout.Row 同一公式）。 */
   grid-template-columns: repeat(
     auto-fit,
     minmax(
-      max(var(--ui-form-column-min), calc((100% - var(--ui-space-2)) / 2)),
+      max(
+        var(--mh-form-column-min),
+        calc((100% - (var(--mh-form-columns) - 1) * var(--mh-form-gap)) / var(--mh-form-columns))
+      ),
       1fr
     )
   );
   align-items: start;
 }
 
+/* 档位只覆盖变量（几何只有一份）。5 / 6 档在默认最小宽 320 下要容器 1632 / 1960px 才排得出来，
+   留着它们是给「宽屏展示页 / 大屏看板」用 —— 配合 `columnMinWidth` 调小最小宽才落地得快。 */
+.mh-form--columns-3 {
+  --mh-form-columns: 3;
+}
+.mh-form--columns-4 {
+  --mh-form-columns: 4;
+}
+.mh-form--columns-5 {
+  --mh-form-columns: 5;
+}
+.mh-form--columns-6 {
+  --mh-form-columns: 6;
+}
+
+/* ===== 动态列数（`columns="auto"`）=====
+ * `auto-fill` + `minmax(最小列宽, 1fr)`：**列数随容器宽度变**，列数 =
+ * `floor((容器宽 + 行距) / (最小宽 + 行距))`。实测（最小宽 320 / 行距 8）：
+ * 640px → 1 列、660px → 2 列、1000px → 3 列、1320px → 4 列；每列宽落在 `[最小宽, 2 × 最小宽)`。
+ *
+ * 为什么是 `auto-fill` 而不是 `auto-fit`：两者只差在「子项少于轨道数」时 ——
+ * `auto-fit` 会**折叠空轨道**，于是宽容器里 2 个字段被拉成两条长条（实测 1400px 下每项 696px）；
+ * `auto-fill` 保留轨道，字段列宽稳定在区间内（1400px 下每项 344px）。表单要的是**列宽稳定**，
+ * 不是「把剩余宽度填满」。 */
+
+.mh-form--columns-auto {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(var(--mh-form-column-min), 1fr));
+  align-items: start;
+}
+
 /* 跨满整行：说明行 / 卡片组 / 表格 / 文本域这类整块内容（单列时 grid-column 无效，无副作用） */
 
 .mh-form-item--full {
@@ -53,20 +115,27 @@
 .mh-form-item {
   /* label 列宽：Item 行内下发 --mh-form-label-width；未传时取令牌 */
   --mh-form-label-width: var(--ui-form-label-width);
-  display: flex;
-  align-items: flex-start;
+  /* 两列：label 列（定宽）+ 控件列（吃满剩余）。控件列写 `minmax(0, 1fr)` 而不是 `1fr`：
+     它必须能被内部长内容压缩，否则长 URL / 自绘表格会撑破列宽。 */
+  display: grid;
+  grid-template-columns: var(--mh-form-label-width) minmax(0, 1fr);
+  /* **第 1 行内交叉轴居中** = label 文字与控件中线对齐。
+     第 1 行的行高由控件（恒高于一行文字）决定 ⇒ 对齐与控件高度**解耦**：
+     控件档位换 sm/md/lg、换主题、放自绘控件都自动成立，**不需要任何「控件高度」常量**。 */
+  align-items: center;
 }
 
 /* label 列：固定宽 + **右对齐**（与 farris 的动态表单一致，也是水平表单的通行默认）。
-   min-height 取**控件真实高度**（--ui-form-control-height 由桥接层按 farris 控件规则给出）：
-   label 盒与控件盒等高 ⇒ 两侧文字各自居中后落在同一条中线上。
-   曾经写的是 32px 令牌，而 farris 控件实际 ≈24px（rem，随根字号）⇒ label 明显偏低，已修。 */
+   只占第 1 行（控件那一行），所以错误 / 说明的出现不会把它带走；
+   本件**不设任何高度** —— 从前用 min-height 取一个外部注入的控件高度来「假装等高」，
+   而那个变量在骨架层没有出处（回退 auto），label 盒退化成一行文字并贴行顶：
+   输入框中线偏高 6px、大号档偏高 10px、文本域偏高 9px。 */
 
 .mh-form-item__label {
-  flex: 0 0 auto;
+  grid-column: 1;
+  grid-row: 1;
   width: var(--mh-form-label-width);
   box-sizing: border-box;
-  min-height: var(--ui-form-control-height, auto);
   padding-right: var(--ui-space-3);
   display: flex;
   align-items: center;
@@ -113,17 +182,57 @@
   white-space: nowrap;
 }
 
+/* 控件列：只装**控件本体**（错误 / 说明是行的直接子节点，自然落第 2 行起）。
+   `min-width: 0` 必须留：grid item 的默认 `min-width: auto` 会让长内容撑破列宽。 */
+
 .mh-form-item__control {
-  flex: 1;
+  grid-column: 2;
+  grid-row: 1;
   min-width: 0;
 }
 
+/* 矮控件（开关 / 勾选框 / 单选）在控件列里**按盒居中**，而不是按行盒的基线排。
+ *
+ * 它们高 14~18px，**比一行文字（20px）还矮**（`Switch` / `Checkbox` / `Radio` 三件即这一族）：
+ * 作为行内元素参与基线对齐时，控件列会被 line box 撑高（实测 22px = 18 + 行内 leading），
+ * 而控件本身在那一行里偏上 2px —— 开关与标签看着就不在一条中线上（本件第 1 行本来是居中的，
+ * 偏的是**控件列内部**这一层）。
+ *
+ * 单子项时把控件列切成 flex 并 `align-items: center`：控件列高度回到控件自身高度，
+ * 与 label 同处第 1 行、各自居中 ⇒ 两侧中线重合（实测 switch 18px / checkbox 14px 偏差都为 0，
+ * 行高也从 22px 回到 20px —— 不再被行盒的 leading 撑高）。
+ *
+ * 为什么限定「**唯一**子项」：控件列里放多个内容时（如「输入框 + 获取按钮」）原本是块级上下堆叠，
+ * 无条件 flex 会把它们排成一行 —— 那是布局变更，不是修对齐。
+ *
+ * 判据是**属性协议** `data-inline-control`，不是元素名、也不是别件的类名：
+ *
+ * - `Switch` / `Checkbox` / `Radio` 在根节点上声明这个属性（三件正好是这一族，14~18px）；
+ * - **自绘的行内小控件**（根是 `div` / `span` 都行）在根上加同一个属性就自动接入 ——
+ *   不需要对齐本库的类名，也不必知道这里的实现；
+ * - 为什么不按元素名判（`label` / `button`）：那把判据绑死在「别人怎么写 DOM」上，
+ *   自绘控件必然漏掉（而控件根是什么元素本就是它的实现自由）；
+ *   按类名判则要求两个面互相引用，本仓既有裁决不允许。
+ *
+ * 对齐**不依赖控件列的高度**（别以为 `display: flex` 让控件列从「撑满行高」变成「内容撑高」
+ * 就把对齐弄丢了）：switch 行三种行级配置实测 —— `center` 控件列 18px、`stretch` 控件列 20px，
+ * switch 中心都落在行中心、与 label 文字同线（Δ 都是 0）；三种里唯一会偏的是 `align="start"`
+ * 顶对齐档（Δ = −10，label 有 9px 上内距而控件贴顶）—— 那一档是给多行 / 整块内容用的，
+ * 开关不要放进那种行，或显式写 `align="center"`。
+ * 将来若要让控件列**占满行高**（例如给它画背景 / 分割线），在行上写 `align-items: stretch`
+ * 或给控件列 `align-self: stretch` 即可 —— 实测那样 switch 依然居中。 */
+
+.mh-form-item__control:has(> [data-inline-control]:only-child) {
+  display: flex;
+  align-items: center;
+}
+
 /* 只读文本行（Form.Item 的 text 形态：摘要 / 详情）：正文色与行高，
-   长文案（SQL where、列说明）按词折行；`pre-wrap` 保留换行符（多行过滤条件回显）。 */
+   长文案（SQL where、列说明）按词折行；`pre-wrap` 保留换行符（多行过滤条件回显）。
+   它只占第 1 行、与 label 各自居中即对齐 —— **不给任何高度**（撑到某个「控件高」等于把那个
+   外部高度变量换个名字复活；只读行按内容高排版，行与行的间距归 `Form` 的 gap）。 */
 
 .mh-form-item__text {
-  /* 与 label 同一口径：桥接层不给 `--ui-form-control-height` 时退回 auto（不给回退会让整条声明作废） */
-  min-height: var(--ui-form-control-height, auto);
   display: flex;
   align-items: center;
   font-size: var(--ui-font-body);
@@ -139,7 +248,12 @@
   color: var(--ui-base-content-subtle);
 }
 
+/* 错误 / 说明：**行的直接子节点**（不在控件列里面），排在控件行之下、与控件列同列。
+   只给 `grid-column` 不给行号 —— 自动放置会把它们推进下一个空行：控件占着第 1 行，
+   于是它们既不会挤进第 1 行、也不会掉到 label 列下面去。 */
+
 .mh-form-item__error {
+  grid-column: 2;
   margin-top: var(--ui-space-1);
   font-size: var(--ui-font-caption);
   line-height: var(--ui-line-caption);
@@ -147,33 +261,99 @@
 }
 
 .mh-form-item__hint {
+  grid-column: 2;
   margin-top: var(--ui-space-1);
   font-size: var(--ui-font-caption);
   line-height: var(--ui-line-caption);
   color: var(--ui-base-content-subtle);
 }
 
+/* ===== 无 label 列（`label` 与 `required` 都没有：整块内容 / 纯说明行）=====
+ * 控件位与提示横跨整行 —— 两列 grid 下第一列必须收掉，否则整块内容会被挤到 label 列宽之后。 */
+.mh-form-item--no-label {
+  grid-template-columns: minmax(0, 1fr);
+}
+.mh-form-item--no-label > .mh-form-item__control,
+.mh-form-item--no-label > .mh-form-item__error,
+.mh-form-item--no-label > .mh-form-item__hint {
+  grid-column: 1 / -1;
+}
+
+/* ===== 行内垂直对齐档 =====
+ * 默认（基类）`center`：label 与控件**中线**对齐 —— 第 1 行行高 = 控件真实高度，
+ * 与控件档位 / 主题 / 自绘控件都无关。需要顶对齐的是**多行与整块内容**：label 该与首行文字齐，
+ * 而不是落到整块高度的中间。
+ *
+ * 自动判定（按控件形态，消费方零配置）：认**原生元素** `textarea`，不认别件的类名（面之间不互指，
+ * 是本仓的既有裁决；认元素还顺带覆盖了代码编辑区这类自绘多行件）。
+ * 文本域的壳带 8px 上内距 + 1px 边框（控件自身内距被壳归零，见 input.css），
+ * label 补上同样的偏移才与**首行文字**同线 —— 不补则仍偏高 9px（实测）。
+ * 整条自动判定包 `:where()`：把选择器特异性压回 0-1-0，显式修饰类（0-2-0）才稳定压过它，
+ * 不必靠「谁写在后面」争胜出。 */
+.mh-form-item:where(:has(.mh-form-item__control textarea)) {
+  align-items: start;
+}
+.mh-form-item:where(:has(.mh-form-item__control textarea)) > .mh-form-item__label {
+  padding-top: calc(var(--ui-space-2) + 1px);
+}
+
+/* 显式档（`Form.Item` 的 `align`）：样式认不出形态的自绘内容（卡片组 / 表格 / 富文本）写 start；
+   要强制回到默认的中线对齐写 center。两者都会压过上面的自动判定。
+   `start` 沿用与文本域**同一口径**的上内距（8px 内距 + 1px 边框）：自绘块自带更大内距时会有几像素差
+   （实测块内距 12px 时差 4px）—— 组件无从知道自绘块内部的排版，要求严格同线时在块内自行调整。 */
+.mh-form-item.mh-form-item--align-start {
+  align-items: start;
+}
+.mh-form-item.mh-form-item--align-start > .mh-form-item__label {
+  padding-top: calc(var(--ui-space-2) + 1px);
+}
+.mh-form-item.mh-form-item--align-center {
+  align-items: center;
+}
+.mh-form-item.mh-form-item--align-center > .mh-form-item__label {
+  padding-top: 0;
+}
+
 /* ===== 纵向排布（`layout="vertical"`：label 在控件上方） =====
- * 窄容器（抽屉 / 移动端）与「字段名很长」的场景用纵向 —— 横向时 label 列宽会把控件压得很窄。 */
+ * 窄容器（抽屉 / 移动端）与「字段名很长」的场景用纵向 —— 横向时 label 列宽会把控件压得很窄。
+ * 单列三行：label / 控件 / 提示依次往下（提示不给行号，自动放置接在控件之后）。
+ * 选择器带 `>` 且写成 0-3-0：纵向档必须压过上面的顶对齐档与显式档 ——
+ * 纵向时 label 本来就在上方，那 9px 上内距只会在 label 上多出一截空隙。 */
 .mh-form--vertical .mh-form-item {
-  flex-direction: column;
-  align-items: stretch;
+  grid-template-columns: minmax(0, 1fr);
 }
-.mh-form--vertical .mh-form-item__label {
+.mh-form--vertical .mh-form-item > .mh-form-item__label {
+  grid-column: 1;
+  grid-row: 1;
   width: auto;
   min-width: 0;
   justify-content: flex-start;
   padding-right: 0;
-  padding-bottom: var(--ui-space-1);
+  padding-top: 0;
+  padding-bottom: var(--ui-space-2);
   text-align: left;
 }
+.mh-form--vertical .mh-form-item > .mh-form-item__control {
+  grid-column: 1;
+  grid-row: 2;
+}
+.mh-form--vertical .mh-form-item > .mh-form-item__error,
+.mh-form--vertical .mh-form-item > .mh-form-item__hint {
+  grid-column: 1;
+}
 
 /* ===== 表单头（`Form.Header`：单头，成员归位到最前）=====
    只做**标题排版**与**右端操作位**，不承担区块分组（那是 `Panel` 的职责）。
    三样（title / extra / description）都没有时组件整块不渲染 —— 空盒子同样占一档
    `Form` 的 gap，会凭空多出间距。 */
 
+/* `grid-column: 1 / -1`：多列下**表头必须跨满整行** —— 它是 `Form` 的一个 grid 子项，
+   不跨行就只占一格（实测 `columns={2}`、容器 800 时表头只有 396px = 半宽；列数越多越窄）。
+   `1 / -1` 引用的是最后一条**显式**轨道线，不会生成隐式轨道，故动态列数下同样安全；
+   单列（flex 形态）时该属性无效、无副作用（与 `.mh-form-item--full` 同款写法）。 */
+
 .mh-form__header {
+  grid-column: 1 / -1;
   display: flex;
   flex-direction: column;
   gap: var(--ui-space-1);

package/dist/styles/components/input.css

@@ -327,7 +327,20 @@
   height: var(--ui-input-affix-size);
 }
 
-/* ===== 清除（有内容才由组件渲染；圆形 + close 字形） ===== */
+/* ===== 清除（有内容才由组件渲染；圆形 + close 字形）=====
+ *
+ * **默认隐形，滑过表壳或聚焦时才显形**：常显会在每一个有内容的输入框右端永远挂一颗深色实心圆点 ——
+ * 密集场景（表格内编辑、筛选条、多选触发器、带前后缀的搜索行）里那一列圆点比字段本身还抢眼，
+ * 也与「清除是低频动作」的层级不符。
+ *
+ * 为什么用 `opacity` 而不是 `display` / `visibility`：
+ * ① 它仍在流中**占位** —— 显隐时输入区宽度不变；换 `display` 会让文字在鼠标移入的一瞬间横跳；
+ * ② 它仍是可命中的**定位元素** —— 触发器形态的整箱热区靠 `position: relative` + DOM 顺序压在
+ *    覆盖层之上（见上一节），换 `visibility: hidden` 会连命中一起关掉，那一块反被热区接管。
+ *
+ * `:focus-within` 是**触屏与键盘**的兜底：没有 hover 的设备上，点进输入框同样要能点到清除
+ * （键盘另有一条 `Delete` 路径，见组件）。禁用档不显形：那时本来就不该清，圆点落在灰底上还会
+ * 被误读成可用。 */
 .mh-input__clear {
   flex: none;
   display: inline-flex;
@@ -344,6 +357,20 @@
   background: var(--ui-base-300); /* 规范 Te10 圆点底 */
   color: var(--ui-base-100);
   cursor: pointer;
+  opacity: 0;
+  transition-property: opacity;
+  transition-duration: 0.15s;
+  transition-timing-function: ease;
+}
+/* 显形：滑过**整件**（内距与附加位区域都算）或任一控件拿到焦点 */
+.mh-input__wrap:hover > .mh-input__clear,
+.mh-input__wrap:focus-within > .mh-input__clear {
+  opacity: 1;
+}
+/* 禁用：整件不可交互，清除位一并收掉（`:has()` 的特异性高于上面那条，故同时压过 hover） */
+.mh-input__wrap:has(> .mh-input:disabled) > .mh-input__clear,
+.mh-input__wrap:has(> .mh-input.is-disabled) > .mh-input__clear {
+  opacity: 0;
 }
 .mh-input__clear:hover,
 .mh-input__clear:active {

package/dist/styles/components/layout.css

@@ -39,6 +39,7 @@
   display: flex;
   flex-direction: column;
   gap: var(--mh-layout-row-gap);
+  /* 内距不在本件声明：由 `padding` prop 直接下发实体 `padding`（值来自 prop） */
   /* 交叉轴（水平）不声明 = CSS 默认的 stretch（子项齐宽）；要居中写 align="center" */
   /* 放开 min-width：行常被塞进窄格子（表格单元格、限宽控件列）——
      不放开的 flex 容器压不进窄格，会把外层撑破 */
@@ -110,6 +111,7 @@
      要贴顶写 align="start"、要齐宽写 align="stretch" */
   align-items: center;
   gap: var(--mh-layout-column-gap);
+  /* 内距不在本件声明：同 `.mh-layout-row`，由 `padding` prop 直接下发 */
   min-width: 0;
 }
 

package/dist/styles/components/steps.css

@@ -13,6 +13,8 @@
  *
  * 连线用**独立空元素**（`.mh-steps__connector`）而不是 `.mh-steps__step + ::after`：折角箭头要撑开弹性余量，
  * 且 N 个节点配 N-1 条线，独立元素才能让两端节点各自保持自己的标题宽度。
+ *
+ * 可点档（`clickable`）下步元素是**原生 `<button>`** —— 归零、焦点环、禁用态见文件中间那节。
  */
 
 /* 几何只挂在 node 档根件上：令牌在同名 `.tokens.css`（锚 `[data-manohub-ui]`），几何若跟着挂会给 bar / 进度条多套一层 flex */
@@ -132,6 +134,52 @@
   filter: drop-shadow(0 4px 5px color-mix(in srgb, var(--ui-primary) 30%, transparent));
 }
 
+/* ===== 可点档与禁用态（`clickable`）=====
+   可点档把步元素换成**原生 `<button>`**（键盘 Tab/Enter、`:focus-visible`、`disabled` 都交浏览器），
+   于是这里只剩两件事：把 UA 默认外观归零、给禁用与焦点一份视觉。 */
+
+/* 归零。**用 `:where()` 把本档特异性压到 0**：它只该清掉 UA 的 button 默认外观，
+   件自己的几何 / 字号 / 配色（上面 `.mh-steps__seg` 那几条）必须原样生效。
+   若用普通类选择器（0-1-0），这里的 `padding: 0` 会与 `.mh-steps__seg` 的
+   `padding-left`（让开燕尾尖）打平、靠源序决胜 —— `:where()` 让那条稳赢，也省得以后
+   调文件顺序就把段条弄坏。 */
+:where(.mh-steps__step--clickable, .mh-steps__seg--clickable) {
+  appearance: none;
+  border: 0;
+  padding: 0;
+  margin: 0;
+  background: none;
+  font: inherit;
+  color: inherit;
+  text-align: inherit;
+  cursor: pointer;
+}
+
+/* 键盘焦点环（与 button / radio / tag 同一句）。
+   外扩 2px 而不是按钮那套 `-2px`：步元素没内距，内缩会把环画在节点圆与标题上 */
+.mh-steps__step--clickable:focus-visible,
+.mh-steps__seg--clickable:focus-visible {
+  outline: 2px solid var(--ui-primary);
+  outline-offset: 2px;
+  border-radius: var(--ui-radius-sm);
+}
+
+/* 禁用态：原生 `disabled` 已经挡住了点击与键盘序列，这里只补视觉。
+   节点 / 段底**不动** —— 它的「已完成 / 当前」状态语义仍然成立，禁用只表示
+   「这一步现在不能跳」，不是「这一步不存在」。
+   段条另排 `:not(--active)`：当前段本来是主色底 + 反白字，把它的字色降成 subtle 会读不清；
+   而且「当前段」本来也不该被画成禁用。 */
+.mh-steps__step--disabled,
+.mh-steps__seg--disabled {
+  cursor: not-allowed;
+}
+.mh-steps__step--disabled .mh-steps__title {
+  color: var(--ui-base-content-subtle);
+}
+.mh-steps__seg--disabled:not(.mh-steps__seg--active) {
+  color: var(--ui-base-content-subtle);
+}
+
 /* ===== 进度条（规范只有令牌、无标记示例；与对话框的进程条共用） ===== */
 .mh-steps__progress {
   height: var(--ui-steps-progress-height);