@xihan-ui/styles 3.0.0 → 3.2.0

package/dist/css/field-array.css

@@ -0,0 +1,226 @@
+/*
+ * 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';
+/* 行的进场与退场取共享关键帧。 */
+@import '../family/motion.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-field-array {
+    --xh-field-array-skin: 1;
+  }
+
+  /* 一行一条，纵向堆叠；新增把手跟在最后一行下面 */
+  .xh-scope-field-array[data-part='root'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-field-array-gap, var(--xh-space-2));
+    /* 删掉的行由替身绝对定位在原处播完退场，定位基准是根节点 */
+    position: relative;
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  .xh-scope-field-array[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 内容在左、把手在右，把手那一列不随内容伸缩 */
+  .xh-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));
+    /* 增删与上移下移带来的换位：由列表动效先反向补偿、再沿这条过渡滑到新位置 */
+    transition: translate var(--xh-motion-duration-move) var(--xh-motion-ease-continuous);
+  }
+
+  /* 新增的行进场，同一批按到达顺序错开；首帧就在的直接呈现（自己或根节点带 data-instant） */
+  .xh-scope-field-array[data-part='item']:not([data-instant], [data-instant] > :where(.xh-scope-field-array)) {
+    animation: xh-item-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong) backwards;
+    animation-delay: calc(var(--xh-_stagger-index, 0) * var(--xh-motion-stagger-step));
+  }
+
+  /* 删掉的行：替身留在原处淡出，播完即移除 */
+  .xh-scope-field-array[data-part='item'][data-state='closed'] {
+    animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
+  .xh-scope-field-array[data-part='item'][hidden] {
+    display: none;
+  }
+
+  /* 行前的行号或名目：不参与分宽，弱一档前景把它与行里的内容分开 */
+  .xh-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;
+  }
+
+  .xh-scope-field-array[data-part='item-label'][hidden] {
+    display: none;
+  }
+
+  /* 行里放什么控件归作者，这里只给它一条能撑开也能收窄的轨道。
+     min-inline-size 归零：不写的话里面的输入框按 UA 默认宽度顶住，长内容会把整行撑破 */
+  .xh-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;
+  }
+
+  .xh-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，家族按后者收掉悬停与按下反馈 */
+  .xh-scope-field-array[data-part='item-delete-trigger'],
+  .xh-scope-field-array[data-part='move-up-trigger'],
+  .xh-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，作者自己收起它时要的是同一条 */
+  .xh-scope-field-array[data-part='item-delete-trigger'][hidden],
+  .xh-scope-field-array[data-part='move-up-trigger'][hidden],
+  .xh-scope-field-array[data-part='move-down-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 删除把手悬停转危险色：它是这一行里唯一不可撤销的动作 */
+  .xh-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，线型由这里给 */
+  .xh-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;
+  }
+
+  .xh-scope-field-array[data-part='add-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
+  .xh-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;
+  }
+
+  .xh-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;
+  }
+
+  .xh-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 声明之后 */
+  .xh-scope-field-array[data-part='item-content'][hidden],
+  .xh-scope-field-array[data-part='item-action'][hidden] {
+    display: none;
+  }
+
+  @media (forced-colors: active) {
+    /* 兜底字形是 mask 挖出来的一块底色，这一档里底色被系统换成 Canvas，字形跟着消失。
+       字形退出强制换色、直接写系统色（不能取 currentColor：退出强制换色的伪元素读到的是被系统换掉之前的作者色）：
+       按钮面上取 ButtonText，悬停与按下时家族把按钮涂成 Highlight、字形换 HighlightText；
+       禁用取 GrayText */
+    .xh-scope-field-array:is([data-part='move-up-trigger'], [data-part='move-down-trigger'], [data-part='item-delete-trigger']):empty::before {
+      forced-color-adjust: none;
+      background-color: ButtonText;
+    }
+
+    .xh-scope-field-array:is([data-part='move-up-trigger'], [data-part='move-down-trigger'], [data-part='item-delete-trigger']):not([data-disabled]):not([data-loading]):is(:hover, :active, [data-pressed]):empty::before {
+      background-color: HighlightText;
+    }
+
+    .xh-scope-field-array:is([data-part='move-up-trigger'], [data-part='move-down-trigger'], [data-part='item-delete-trigger'])[data-disabled]:empty::before {
+      background-color: GrayText;
+    }
+  }
+}

package/dist/css/field.css

@@ -0,0 +1,166 @@
+/*
+ * 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 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-field {
+    --xh-field-skin: 1;
+  }
+
+  .xh-scope-field[data-part='root'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-field-gap, var(--xh-space-1));
+    /* 字段族控件放进字段即铺满字段宽：字段的宽由表单的列给，控件跟着列走，
+       不必逐个组件在根上写 inline-size: 100%。单独摆放的控件仍是 16rem 缺省宽；
+       单类钉宽（--xh-<组件>-control-w）照旧压过这一条 */
+    --xh-control-w: 100%;
+  }
+
+  /* 表单横排（标签左置）：字段转两列网格，标签列宽由表单的 --xh-form-label-w 统一给，
+     整表据此对齐；描述与错误文案跟着控件走第二列 */
+  .xh-scope-form[data-part='root'][data-layout='horizontal'] .xh-scope-field[data-part='root'] {
+    display: grid;
+    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;
+  }
+
+  .xh-scope-form[data-part='root'][data-layout='horizontal'] .xh-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);
+  }
+
+  .xh-scope-form[data-part='root'][data-layout='horizontal'][data-label-align='start'] .xh-scope-field[data-part='label'] {
+    justify-self: start;
+  }
+
+  .xh-scope-form[data-part='root'][data-layout='horizontal'] .xh-scope-field[data-part='root'] > :not([data-part='label']) {
+    grid-column: 2;
+  }
+
+  .xh-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));
+    /* 转无效或转禁用时标签换色，两档之间接一段过渡（与字段集组标题同一档） */
+    transition: color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  .xh-scope-field[data-part='label'][data-disabled] {
+    color: var(--xh-field-label-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* 必填星号的字形、间距与默认色在 label.css 公共层；这里只把颜色接到本组件的覆盖槽上 */
+  .xh-scope-field[data-part='label'][data-required]::after {
+    color: var(--xh-field-label-star, var(--xh-fg-danger));
+  }
+
+  /* control 是作者自己的输入控件，它自身就是视觉盒：描边、底、影、圆角与悬停 / 聚焦 / 无效 /
+     只读 / 禁用各态由 Field Chrome 家族配方按连接层投影的 data-xh-field-chrome 画，
+     这里只把既有使用者槽映射到家族桥接槽。Field 没有 size 轴，尺寸私有槽按连接层固定投的 md 档取值。
+     使用者槽与桥接槽同在 --xh-field- 前缀下：圆角那一位（--xh-field-control-radius）与家族读的桥接槽同名，
+     使用者写它即被家族直接读到，无法再经映射中转，圆角在这里按同一槽同一缺省直接声明（与家族算出的值一致，
+     只为把这一位使用者槽留在皮肤的消费位上）；其余各位逐条对齐，不与桥接槽撞名 */
+  .xh-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));
+    /* 焦点环与家族同一支公共环，不再留逐组件的环色槽（焦点边与环一律公共） */
+    --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%;
+    border-radius: var(--xh-field-control-radius, var(--xh-shape-control));
+    /* 家族 chrome 不设字号：控件自身就是盒，正文字号由这里给 */
+    font-size: var(--xh-field-control-font-size, var(--xh-text-body-size));
+  }
+
+  /* 无效标签色的默认在 label.css 公共层；这里只把颜色接到本组件的覆盖槽上 */
+  .xh-scope-field[data-part='label'][data-invalid] {
+    color: var(--xh-field-label-fg-invalid, var(--xh-fg-danger));
+  }
+
+  /* 说明与错误文案的角色（外边距、行距、默认字号与字色）在 description.css 公共层；
+     这里只把字色与字号接到本组件的覆盖槽上 */
+  .xh-scope-field[data-part='description'] {
+    color: var(--xh-field-description-fg, var(--xh-fg-muted));
+    font-size: var(--xh-field-description-font-size, var(--xh-text-secondary-size));
+    /* 与标签同一档过渡：整个字段转禁用时两处一起变淡 */
+    transition: color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  .xh-scope-field[data-part='description'][data-disabled] {
+    color: var(--xh-field-description-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  .xh-scope-field[data-part='error-text'] {
+    color: var(--xh-field-error-fg, var(--xh-fg-danger));
+    font-size: var(--xh-field-error-font-size, var(--xh-text-secondary-size));
+  }
+
+  /* 辅助文字那一行的占位：字段渲染了错误文案、当前又没在报错时，收起的错误文案自己留在流里占住一行
+     （不可见、不进可及树），与报错时的错误文案等高。字段的外框高度前后一样，表单不会因为一段错误文字
+     重新排版，定高或限高的父级里也不会把控件挤出去；退场就在这一行里淡出，播完才藏起。
+
+     没有在场的 description 才这样占：描述已经占着这一行了，报错时由描述让位给错误文案（见 description.css），
+     收起的错误文案按公共层不占位。没渲染错误文案的字段本来就没有这一行。
+
+     高度按错误文案那一档的字号乘行距算，得到的正是它一行的高度。
+     不写 1lh：那个单位晚于本库声明的浏览器地板，取不到时整条声明被丢弃、占位高退回 0，
+     字段又会随报错撑高一次，而这种失效不报错。
+     与前一块的距离由根的 gap 给，和错误文案顶上来时是同一段；横排表单里它与别的子块一样落在控件那一列。 */
+  .xh-scope-field[data-part='root']:not(:has(> .xh-scope-field[data-part='description']:not([hidden])))
+    > .xh-scope-field[data-part='error-text'][hidden] {
+    position: static;
+    block-size: calc(
+      var(--xh-field-error-font-size, var(--xh-text-secondary-size)) * var(--xh-leading-normal)
+    );
+    transition:
+      opacity var(--xh-motion-duration-exit) var(--xh-motion-ease-exit),
+      visibility 0s var(--xh-motion-duration-exit);
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  .xh-scope-field[data-part='root'][hidden],
+  .xh-scope-form[data-part='root'][hidden] {
+    display: none;
+  }
+}

package/dist/css/fieldset.css

@@ -0,0 +1,102 @@
+/*
+ * 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 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-fieldset {
+    --xh-fieldset-skin: 1;
+  }
+
+  /* 抹掉 UA 给 <fieldset> 的边框、内外边距与 min-content 下限，间距全部改由令牌给。
+     display 落在 fieldset 的匿名内容盒上：首个 <legend> 不在这个盒子里，
+     所以 gap 只作用于组内各块，legend 与内容之间的留白由 legend 自己的下外边距给。 */
+  .xh-scope-fieldset[data-part='root'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-fieldset-gap, var(--xh-space-4));
+    margin: 0;
+    border: 0;
+    padding: 0;
+    min-inline-size: 0;
+  }
+
+  .xh-scope-fieldset[data-part='root'][hidden] {
+    display: none;
+  }
+
+  .xh-scope-fieldset[data-part='legend'] {
+    padding: 0;
+    margin-block-end: var(--xh-fieldset-legend-gap, var(--xh-space-2));
+    /* 组标题是「一组字段的标题」，归集合标题角色：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);
+  }
+
+  /* 整组无效时组标题转警示色：没渲染错误文案的字段集上，这是屏幕上唯一变化的东西。
+     默认色在 label.css 公共层，这里只把颜色接到本组件的覆盖槽上 */
+  .xh-scope-fieldset[data-part='legend'][data-invalid] {
+    color: var(--xh-fieldset-legend-fg-invalid, var(--xh-fg-danger));
+  }
+
+  /* 整组禁用时组标题跟着变淡；组内控件由原生 fieldset[disabled] 各自呈现禁用态。
+     选择器权重高于上一条且排在后面，禁用与无效同时为真时以禁用为准。 */
+  .xh-scope-fieldset[data-part='root'] > .xh-scope-fieldset[data-part='legend'][data-disabled] {
+    color: var(--xh-fieldset-legend-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* 必填星号的字形、间距与默认色在 label.css 公共层；这里只把颜色接到本组件的覆盖槽上 */
+  .xh-scope-fieldset[data-part='legend'][data-required]::after {
+    color: var(--xh-fieldset-legend-star, var(--xh-fg-danger));
+  }
+
+  /* 说明与错误文案的角色（外边距、行距、默认字号与字色）在 description.css 公共层；
+     这里只把字色与字号接到本组件的覆盖槽上 */
+  .xh-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);
+  }
+
+  .xh-scope-fieldset[data-part='description'][data-disabled] {
+    color: var(--xh-fieldset-description-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* 并排字段的一段：窄屏一列，够宽了按列宽自动分栏。列宽下限由槽给，作者按字段类型改 */
+  .xh-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;
+  }
+
+  .xh-scope-fieldset[data-part='field-group'][hidden] {
+    display: none;
+  }
+
+  /* 组末尾那一行按钮：靠尾端排，窄屏换行 */
+  .xh-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));
+  }
+
+  .xh-scope-fieldset[data-part='actions'][hidden] {
+    display: none;
+  }
+
+  .xh-scope-fieldset[data-part='error-text'] {
+    color: var(--xh-fieldset-error-fg, var(--xh-fg-danger));
+    font-size: var(--xh-fieldset-error-font-size, var(--xh-text-secondary-size));
+  }
+}