@xihan-ui/styles 1.0.0 → 2.0.0

package/css/field-array.css

@@ -0,0 +1,190 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 field array 样式。 */
+
+/* FieldArray 独立皮肤同时传递引入把手的动作控件配方；full bundle 递归去重。 */
+@import '../family/action-control.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='field-array'] {
+    --xh-field-array-skin: 1;
+  }
+
+  /* 一行一条，纵向堆叠；新增把手跟在最后一行下面 */
+  [data-scope='field-array'][data-part='root'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-field-array-gap, var(--xh-space-2));
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  [data-scope='field-array'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 内容在左、把手在右，把手那一列不随内容伸缩 */
+  [data-scope='field-array'][data-part='item'] {
+    display: flex;
+    align-items: center;
+    gap: var(--xh-field-array-item-gap, var(--xh-space-2));
+    padding: var(--xh-field-array-item-padding, var(--xh-space-0));
+    border-radius: var(--xh-field-array-item-radius, var(--xh-shape-surface));
+  }
+
+  [data-scope='field-array'][data-part='item'][hidden] {
+    display: none;
+  }
+
+  /* 行前的行号或名目：不参与分宽，弱一档前景把它与行里的内容分开 */
+  [data-scope='field-array'][data-part='item-label'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    color: var(--xh-field-array-item-label-fg, var(--xh-fg-muted));
+    font-size: var(--xh-field-array-item-label-font-size, var(--xh-text-secondary-size));
+    line-height: var(--xh-leading-none);
+    white-space: nowrap;
+  }
+
+  [data-scope='field-array'][data-part='item-label'][hidden] {
+    display: none;
+  }
+
+  /* 行里放什么控件归作者，这里只给它一条能撑开也能收窄的轨道。
+     min-inline-size 归零：不写的话里面的输入框按 UA 默认宽度顶住，长内容会把整行撑破 */
+  [data-scope='field-array'][data-part='item-content'] {
+    display: flex;
+    flex: 1 1 auto;
+    align-items: center;
+    gap: var(--xh-field-array-content-gap, var(--xh-space-2));
+    min-inline-size: 0;
+  }
+
+  [data-scope='field-array'][data-part='item-action'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    gap: var(--xh-field-array-action-gap, var(--xh-space-1));
+  }
+
+  /* —— 行内三个把手 ——
+     只有字形的离散动作钮：盒几何、悬停 / 按下与 0.97 按压、粗指针热区、焦点环、禁用面全由 Action Control 的
+     icon ghost 档给（连接层投 xs：24px 正方盒，行级把手贴着一个控件高的行，取行内动作钮那一档），
+     组件只映射既有使用者槽。静息透明，白底承载 hover 100 → pressed 200。
+     按不动的把手由连接层同时打 aria-disabled 与 data-disabled，家族按后者收掉悬停与按下反馈 */
+  [data-scope='field-array'][data-part='item-delete-trigger'],
+  [data-scope='field-array'][data-part='move-up-trigger'],
+  [data-scope='field-array'][data-part='move-down-trigger'] {
+    --xh-action-visual-size: var(--xh-field-array-trigger-size, var(--xh-_action-profile-visual-size));
+    --xh-action-min-inline-size: var(--xh-field-array-trigger-size, var(--xh-_action-profile-visual-size));
+    --xh-action-radius: var(--xh-field-array-trigger-radius, var(--xh-shape-control));
+    --xh-action-bg-rest: var(--xh-field-array-trigger-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-field-array-trigger-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-field-array-trigger-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-field-array-trigger-fg, var(--xh-fg-muted));
+    --xh-action-fg-hover: var(--xh-field-array-trigger-fg-hover, var(--xh-fg-default));
+    --xh-action-fg-pressed: var(--xh-field-array-trigger-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-field-array-trigger-font-size, var(--xh-text-secondary-size));
+    /* 作者塞进把手的图标与皮肤画的兜底字形同一把尺：按档取字形尺寸。
+       配方尚未把 profile 字形档灌进 --xh-icon-size，钮内字形先按 icon 档逐钮取值 */
+    --xh-icon-size: var(--xh-field-array-icon-size, var(--xh-_action-profile-glyph-size));
+
+    border-width: 0;
+  }
+
+  /* 不换序时连接层给换序把手写 hidden；家族那条 display 会把 UA 的 [hidden]{display:none}
+     盖掉，少了这条把手还留在原地。删除把手同样声明了 display，作者自己收起它时要的是同一条 */
+  [data-scope='field-array'][data-part='item-delete-trigger'][hidden],
+  [data-scope='field-array'][data-part='move-up-trigger'][hidden],
+  [data-scope='field-array'][data-part='move-down-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 删除把手悬停转危险色：它是这一行里唯一不可撤销的动作 */
+  [data-scope='field-array'][data-part='item-delete-trigger'] {
+    --xh-action-fg-hover: var(--xh-field-array-item-delete-fg-hover, var(--xh-fg-danger-hover));
+    --xh-action-fg-pressed: var(--xh-field-array-item-delete-fg-hover, var(--xh-fg-danger-hover));
+  }
+
+  /* —— 新增把手 ——
+     带文案的离散动作钮，走 text outline 档（中性描边、透明底，hover 100 → pressed 200），高一个控件；
+     虚线描边把它和行里的实心控件区分开：它加的是行，不是行里的值——家族只写 border-color，线型由这里给 */
+  [data-scope='field-array'][data-part='add-trigger'] {
+    --xh-action-visual-size: var(--xh-field-array-add-height, var(--xh-_action-profile-visual-size));
+    --xh-action-padding-inline: var(--xh-field-array-add-px, var(--xh-_action-profile-padding-inline));
+    --xh-action-gap: var(--xh-field-array-action-gap, var(--xh-space-1));
+    --xh-action-radius: var(--xh-field-array-add-radius, var(--xh-shape-control));
+    --xh-action-bg-rest: var(--xh-field-array-add-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-field-array-add-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-field-array-add-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-field-array-add-fg, var(--xh-fg-brand));
+    --xh-action-fg-hover: var(--xh-field-array-add-fg, var(--xh-fg-brand));
+    --xh-action-fg-pressed: var(--xh-field-array-add-fg, var(--xh-fg-brand));
+    --xh-action-border-rest: var(--xh-field-array-add-border, var(--xh-_action-variant-border-rest));
+    --xh-action-border-hover: var(--xh-field-array-add-border-hover, var(--xh-_action-variant-border-hover));
+    --xh-action-border-disabled: var(--xh-field-array-add-border-disabled, var(--xh-_action-variant-border-disabled));
+    --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-field-array-add-font-size, var(--xh-text-label-size));
+    --xh-icon-size: var(--xh-field-array-icon-size, var(--xh-_action-profile-glyph-size));
+
+    align-self: flex-start;
+    border-style: dashed;
+  }
+
+  [data-scope='field-array'][data-part='add-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
+  [data-scope='field-array'][data-part='move-up-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-chevron-up) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-up) center / contain no-repeat;
+  }
+
+  [data-scope='field-array'][data-part='move-down-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-chevron-down) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-down) center / contain no-repeat;
+  }
+
+  [data-scope='field-array'][data-part='item-delete-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-close) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-close) center / contain no-repeat;
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  [data-scope='field-array'][data-part='item-content'][hidden],
+  [data-scope='field-array'][data-part='item-action'][hidden] {
+    display: none;
+  }
+}

package/css/field.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.
+ */
+
+/* 定义 field 样式。 */
+
+/* Field 独立皮肤同时传递引入字段视觉盒；full bundle 递归去重。 */
+@import '../family/field-chrome.css';
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='field'] {
@@ -14,7 +24,7 @@
      整表据此对齐；描述与错误文案跟着控件走第二列 */
   [data-scope='form'][data-part='root'][data-layout='horizontal'] [data-scope='field'][data-part='root'] {
     display: grid;
-    grid-template-columns: var(--xh-form-label-w) minmax(0, 1fr);
+    grid-template-columns: var(--xh-form-label-w, 30%) minmax(0, 1fr);
     column-gap: var(--xh-field-label-gap, var(--xh-space-3));
     align-items: start;
   }
@@ -22,9 +32,16 @@
   [data-scope='form'][data-part='root'][data-layout='horizontal'] [data-scope='field'][data-part='label'] {
     grid-column: 1;
     justify-self: end;
+    /* 横排下标签与控件是左右两列，间距归 --xh-field-label-gap 管，竖排那段补白在这儿清零 */
+    margin-block-end: 0;
     /* 与控件的首行文字对齐：行高保持正文行距（标签折行时每行不会撑成一个控件高），
        上下留白把单行文本盒撑到控件高度；配的是哪一档控件由 --xh-field-control-h 告诉它 */
     line-height: var(--xh-field-label-leading, var(--xh-leading-normal));
+    /* 级联兜底：先写一行的高度算式（标签字号 × 标签行距），再写 1lh。
+       1lh 晚于本库声明的浏览器地板，取不到时旧引擎丢掉后一条、留下前一条。
+       两条取的是同一组槽——字号来自本文件里标签那条 font-size、行距来自紧邻上一行，
+       所以算出来是同一个数，使用者覆盖任一槽两条一起跟着走。 */
+    padding-block: calc((var(--xh-field-control-h, var(--xh-control-h-md)) - var(--xh-field-label-font-size, var(--xh-text-label-size)) * var(--xh-field-label-leading, var(--xh-leading-normal))) / 2);
     padding-block: calc((var(--xh-field-control-h, var(--xh-control-h-md)) - 1lh) / 2);
   }
 
@@ -36,69 +53,105 @@
     grid-column: 2;
   }
 
+  /* 横排下这一列是网格的自动流，占位块跟着控件走第二列（选择器不匹配伪元素，单列一条） */
+  [data-scope='form'][data-part='root'][data-layout='horizontal'] [data-scope='field'][data-part='root']::after {
+    grid-column: 2;
+  }
+
   [data-scope='field'][data-part='label'] {
+    /* 一段不带空格的长标识（字段名、英文标识符）在窄处从词内断开：
+       横排表单里标签列是一段比例宽度，这行让标签在那一列里折行，而不是从列的左边顶出去 */
+    overflow-wrap: anywhere;
+    /* 竖排时标签与控件之间的距离：容器的 gap 之上补一段差值，
+       --xh-field-label-gap-block 给多少最终就是多少；不给时差值算成 0，
+       这段距离仍由 --xh-field-gap 与描述、错误文案那两段同宽。 */
+    margin-block-end: calc(
+      var(--xh-field-label-gap-block, var(--xh-field-gap, var(--xh-space-1))) - var(--xh-field-gap, var(--xh-space-1))
+    );
     color: var(--xh-field-label-fg, var(--xh-fg-default));
     font-size: var(--xh-field-label-font-size, var(--xh-text-label-size));
     font-weight: var(--xh-field-label-font-weight, var(--xh-text-label-weight));
-    line-height: var(--xh-leading-none);
   }
 
   [data-scope='field'][data-part='label'][data-disabled] {
     color: var(--xh-field-label-fg-disabled, var(--xh-fg-subtle));
   }
 
-  /* 必填星号：跟着根上的 data-required 亮，选填不标 */
-  [data-scope='field'][data-part='root'][data-required] [data-part='label']::after {
-    content: var(--xh-glyph-mark-required);
-    margin-inline-start: var(--xh-space-1);
+  /* 必填星号的字形、间距与默认色在 label.css 公共层；这里只把颜色接到本组件的覆盖槽上 */
+  [data-scope='field'][data-part='label'][data-required]::after {
     color: var(--xh-field-label-star, var(--xh-fg-danger));
   }
 
-  /* control 是作者自己的输入控件，这里只给一套可被覆盖的基础皮肤 */
+  /* control 是作者自己的输入控件，它自身就是视觉盒：描边、底、影、圆角与悬停 / 聚焦 / 无效 /
+     只读 / 禁用各态由 Field Chrome 家族配方按连接层投影的 data-xh-field-chrome 画，
+     这里只把既有使用者槽映射到家族桥接槽。Field 没有 size 轴，尺寸私有槽按连接层固定投的 md 档取值。
+     使用者槽与桥接槽同在 --xh-field- 前缀下：圆角那一位（--xh-field-control-radius）与家族读的桥接槽同名，
+     使用者写它即被家族直接读到，无法再经映射中转，圆角在这里按同一槽同一缺省直接声明（与家族算出的值一致，
+     只为把这一位使用者槽留在皮肤的消费位上）；其余各位逐条对齐，不与桥接槽撞名 */
   [data-scope='field'][data-part='control'] {
+    --xh-field-control-height: var(--xh-field-control-h, var(--xh-_field-size-control-height));
+    --xh-field-control-padding-inline: var(--xh-field-control-px, var(--xh-_field-size-padding-inline));
+    --xh-field-bg-rest: var(--xh-field-control-bg, var(--xh-_field-variant-bg-rest));
+    --xh-field-bg-hover: var(--xh-field-control-bg-hover, var(--xh-_field-variant-bg-hover));
+    --xh-field-bg-read-only: var(--xh-field-control-bg-readonly, var(--xh-_field-variant-bg-read-only));
+    --xh-field-bg-disabled: var(--xh-field-control-bg-disabled, var(--xh-_field-variant-bg-disabled));
+    --xh-field-fg-rest: var(--xh-field-control-fg, var(--xh-fg-default));
+    --xh-field-border-rest: var(--xh-field-control-border, var(--xh-_field-variant-border-rest));
+    --xh-field-border-hover: var(--xh-field-control-border-hover, var(--xh-_field-variant-border-hover));
+    --xh-field-border-focus: var(--xh-field-control-border-focus, var(--xh-_field-variant-border-focus));
+    --xh-field-border-invalid: var(--xh-field-control-border-invalid, var(--xh-_field-variant-border-invalid));
+    /* 焦点环与家族同一支公共环，不再留逐组件的环色槽（§7.2.5 焦点边与环一律公共） */
+    --xh-field-ring-focus: var(--xh-ring-focus);
+    --xh-field-ring-invalid: var(--xh-ring-invalid);
+    --xh-field-shadow-rest: var(--xh-field-control-shadow, none);
+
     inline-size: 100%;
-    block-size: var(--xh-field-control-h, var(--xh-control-h-md));
-    padding-inline: var(--xh-field-control-px, var(--xh-control-px-md));
-    border: var(--xh-stroke-thin) solid var(--xh-field-control-border, var(--xh-border-control));
     border-radius: var(--xh-field-control-radius, var(--xh-shape-control));
-    background: var(--xh-field-control-bg, var(--xh-bg-canvas));
-    color: var(--xh-field-control-fg, var(--xh-fg-default));
+    /* 家族 chrome 不设字号：控件自身就是盒，正文字号由这里给 */
     font-size: var(--xh-field-control-font-size, var(--xh-text-body-size));
   }
 
-  [data-scope='field'][data-part='control']:focus-visible {
-    border-color: var(--xh-field-control-border-focus, var(--xh-_tone, var(--xh-border-control-focus)));
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
-  }
-
-  [data-scope='field'][data-part='control'][data-invalid] {
-    border-color: var(--xh-field-control-border-invalid, var(--xh-border-invalid));
-  }
-
-  /* 禁用由作者在控件上落原生 disabled，样式统一走 data-disabled */
-  [data-scope='field'][data-part='control'][data-disabled] {
-    background: var(--xh-field-control-bg-disabled, var(--xh-bg-subtle));
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
+  /* 无效标签色的默认在 label.css 公共层；这里只把颜色接到本组件的覆盖槽上 */
+  [data-scope='field'][data-part='label'][data-invalid] {
+    color: var(--xh-field-label-fg-invalid, var(--xh-fg-danger));
   }
 
+  /* 说明与错误文案的角色（外边距、行距、默认字号与字色）在 description.css 公共层；
+     这里只把字色与字号接到本组件的覆盖槽上 */
   [data-scope='field'][data-part='description'] {
-    margin: 0;
     color: var(--xh-field-description-fg, var(--xh-fg-muted));
     font-size: var(--xh-field-description-font-size, var(--xh-text-secondary-size));
-    line-height: var(--xh-leading-normal);
   }
 
   [data-scope='field'][data-part='description'][data-disabled] {
     color: var(--xh-field-description-fg-disabled, var(--xh-fg-subtle));
   }
 
-  /* 不 invalid 时节点带 hidden：此处不声明 display，交给浏览器的 [hidden] 规则收起 */
   [data-scope='field'][data-part='error-text'] {
-    margin: 0;
     color: var(--xh-field-error-fg, var(--xh-fg-danger));
     font-size: var(--xh-field-error-font-size, var(--xh-text-secondary-size));
+  }
+
+  /* 辅助文字那一行的占位：字段渲染了错误文案、当前又没在报错时，补一个与错误文案等高的空块。
+     报错时这个空块让位给错误文案，字段的外框高度前后一样，表单不会因为一段错误文字重新排版，
+     定高或限高的父级里也不会把控件挤出去。
+
+     两个条件缺一不可：
+     渲染了 error-text 且它带 hidden——没有错误文案可显示的字段不占这一行；
+     没有在场的 description——描述已经占着这一行了，报错时由描述让位给错误文案（见 description.css）。
+
+     高度按错误文案那一档的字号乘行距算，得到的正是它一行的高度。
+     不写 1lh：那个单位晚于本库声明的浏览器地板，取不到时整条声明被丢弃、占位高退回 0，
+     字段又会随报错撑高一次，而这种失效不报错。
+     与前一块的距离由根的 gap 给，和错误文案顶上来时是同一段。 */
+  [data-scope='field'][data-part='root']:has(> [data-scope='field'][data-part='error-text'][hidden]):not(
+      :has(> [data-scope='field'][data-part='description']:not([hidden]))
+    )::after {
+    content: '';
+    block-size: calc(
+      var(--xh-field-error-font-size, var(--xh-text-secondary-size)) * var(--xh-leading-normal)
+    );
+    font-size: var(--xh-field-error-font-size, var(--xh-text-secondary-size));
     line-height: var(--xh-leading-normal);
   }
 

package/css/fieldset.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.
+ */
+
+/* 定义 fieldset 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='fieldset'] {
@@ -24,46 +31,72 @@
   [data-scope='fieldset'][data-part='legend'] {
     padding: 0;
     margin-block-end: var(--xh-fieldset-legend-gap, var(--xh-space-2));
-    color: var(--xh-fieldset-legend-fg, var(--xh-fg-default));
+    /* 组标题是「一组字段的标题」，归集合标题角色（§6.4）：fg-muted，与组 --xh-space-2，字号字重同字段标签 */
+    color: var(--xh-fieldset-legend-fg, var(--xh-fg-muted));
     font-size: var(--xh-fieldset-legend-font-size, var(--xh-text-label-size));
     font-weight: var(--xh-fieldset-legend-font-weight, var(--xh-text-label-weight));
     line-height: var(--xh-leading-tight);
+    /* 整组转无效或转禁用时组标题换色，两档之间接一段过渡 */
+    transition: color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
-  /* 整组无效时组标题转警示色：没渲染错误文案的字段集上，这是屏幕上唯一变化的东西 */
-  [data-scope='fieldset'][data-part='root'][data-invalid] > [data-scope='fieldset'][data-part='legend'] {
+  /* 整组无效时组标题转警示色：没渲染错误文案的字段集上，这是屏幕上唯一变化的东西。
+     默认色在 label.css 公共层，这里只把颜色接到本组件的覆盖槽上 */
+  [data-scope='fieldset'][data-part='legend'][data-invalid] {
     color: var(--xh-fieldset-legend-fg-invalid, var(--xh-fg-danger));
   }
 
   /* 整组禁用时组标题跟着变淡；组内控件由原生 fieldset[disabled] 各自呈现禁用态。
-     选择器与上一条同权重且排在后面，禁用与无效同时为真时以禁用为准。 */
+     选择器权重高于上一条且排在后面，禁用与无效同时为真时以禁用为准。 */
   [data-scope='fieldset'][data-part='root'] > [data-scope='fieldset'][data-part='legend'][data-disabled] {
     color: var(--xh-fieldset-legend-fg-disabled, var(--xh-fg-subtle));
   }
 
-  /* 必填星号：跟着根上的 data-required 亮，选填不标 */
-  [data-scope='fieldset'][data-part='root'][data-required] > [data-scope='fieldset'][data-part='legend']::after {
-    content: var(--xh-glyph-mark-required);
-    margin-inline-start: var(--xh-space-1);
+  /* 必填星号的字形、间距与默认色在 label.css 公共层；这里只把颜色接到本组件的覆盖槽上 */
+  [data-scope='fieldset'][data-part='legend'][data-required]::after {
     color: var(--xh-fieldset-legend-star, var(--xh-fg-danger));
   }
 
-  [data-scope='fieldset'][data-part='helper-text'] {
-    margin: 0;
-    color: var(--xh-fieldset-helper-fg, var(--xh-fg-muted));
-    font-size: var(--xh-fieldset-helper-font-size, var(--xh-text-secondary-size));
-    line-height: var(--xh-leading-normal);
+  /* 说明与错误文案的角色（外边距、行距、默认字号与字色）在 description.css 公共层；
+     这里只把字色与字号接到本组件的覆盖槽上 */
+  [data-scope='fieldset'][data-part='description'] {
+    color: var(--xh-fieldset-description-fg, var(--xh-fg-muted));
+    font-size: var(--xh-fieldset-description-font-size, var(--xh-text-secondary-size));
+    /* 与组标题同一档过渡：整组转禁用时两处一起变淡 */
+    transition: color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='fieldset'][data-part='description'][data-disabled] {
+    color: var(--xh-fieldset-description-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* 并排字段的一段：窄屏一列，够宽了按列宽自动分栏。列宽下限由槽给，作者按字段类型改 */
+  [data-scope='fieldset'][data-part='field-group'] {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(var(--xh-fieldset-field-group-col-w, var(--xh-layout-col-min-sm)), 1fr));
+    gap: var(--xh-fieldset-field-group-gap, var(--xh-space-3));
+    align-items: start;
   }
 
-  [data-scope='fieldset'][data-part='helper-text'][data-disabled] {
-    color: var(--xh-fieldset-helper-fg-disabled, var(--xh-fg-subtle));
+  [data-scope='fieldset'][data-part='field-group'][hidden] {
+    display: none;
+  }
+
+  /* 组末尾那一行按钮：靠尾端排，窄屏换行 */
+  [data-scope='fieldset'][data-part='actions'] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: flex-end;
+    gap: var(--xh-fieldset-actions-gap, var(--xh-space-2));
+  }
+
+  [data-scope='fieldset'][data-part='actions'][hidden] {
+    display: none;
   }
 
-  /* 不 invalid 时节点带 hidden：此处不声明 display，交给浏览器的 [hidden] 规则收起 */
   [data-scope='fieldset'][data-part='error-text'] {
-    margin: 0;
     color: var(--xh-fieldset-error-fg, var(--xh-fg-danger));
     font-size: var(--xh-fieldset-error-font-size, var(--xh-text-secondary-size));
-    line-height: var(--xh-leading-normal);
   }
 }