@xihan-ui/styles 1.0.0 → 2.0.0

package/css/separator.css

@@ -1,12 +1,29 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 separator 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='separator'] {
     --xh-separator-skin: 1;
   }
 
+  /*
+   * 线的颜色与线型都先收进两个私有槽，再由 root（只有它一个时）与 line（有分节文字时）
+   * 各自取用：换档只改槽，画在哪个节点上互不影响。
+   */
   [data-scope='separator'][data-part='root'] {
+    --xh-_separator-color: var(--xh-separator-color, var(--xh-material-frosted-separator));
+    --xh-_separator-dash: var(--xh-separator-dash-length, var(--xh-space-1_5));
+    --xh-_separator-dash-gap: var(--xh-separator-dash-gap, var(--xh-space-1_5));
+    --xh-_separator-paint: var(--xh-_separator-color);
+
     border: 0;
-    background: var(--xh-separator-color, var(--xh-border-default));
+    border-radius: var(--xh-separator-radius, var(--xh-shape-pill));
+    background: var(--xh-_separator-paint);
   }
 
   [data-scope='separator'][data-part='root'][data-orientation='horizontal'] {
@@ -19,4 +36,87 @@
     inline-size: var(--xh-separator-thickness, var(--xh-stroke-thin));
     block-size: 100%;
   }
+
+  /* —— 形态 ——
+     三档只换线的深浅，缺省档写在上面的基础规则里。使用者槽排在档值前面，
+     写了 --xh-separator-color 的那一条仍然压过档值 */
+  [data-scope='separator'][data-part='root'][data-variant='subtle'] {
+    --xh-_separator-color: var(--xh-separator-color, var(--xh-material-soft-separator));
+  }
+
+  [data-scope='separator'][data-part='root'][data-variant='strong'] {
+    --xh-_separator-color: var(--xh-separator-color, var(--xh-border-strong));
+  }
+
+  /* —— 虚线 ——
+     实线段与空白段交替铺；方向由 data-orientation 选，表达式只写这两条 */
+  [data-scope='separator'][data-part='root'][data-dashed][data-orientation='horizontal'] {
+    --xh-_separator-paint: repeating-linear-gradient(
+      to right,
+      var(--xh-_separator-color) 0 var(--xh-_separator-dash),
+      transparent var(--xh-_separator-dash) calc(var(--xh-_separator-dash) + var(--xh-_separator-dash-gap))
+    );
+  }
+
+  [data-scope='separator'][data-part='root'][data-dashed][data-orientation='vertical'] {
+    --xh-_separator-paint: repeating-linear-gradient(
+      to bottom,
+      var(--xh-_separator-color) 0 var(--xh-_separator-dash),
+      transparent var(--xh-_separator-dash) calc(var(--xh-_separator-dash) + var(--xh-_separator-dash-gap))
+    );
+  }
+
+  /* —— 带分节文字的三段形态 ——
+     渲染了 content 之后 root 改当容器：自己不再画线，线交给两条 line。
+     形态由部件在不在决定，没有开关 */
+  [data-scope='separator'][data-part='root']:has([data-part='content']) {
+    display: flex;
+    align-items: center;
+    inline-size: 100%;
+    block-size: auto;
+    gap: var(--xh-separator-gap, var(--xh-space-3));
+    background: none;
+  }
+
+  [data-scope='separator'][data-part='root'][data-orientation='vertical']:has([data-part='content']) {
+    flex-direction: column;
+    inline-size: auto;
+    block-size: 100%;
+  }
+
+  /* 两条线等分剩下的地方；粗细与颜色跟 root 单节点时同源 */
+  [data-scope='separator'][data-part='line'] {
+    flex: 1 1 0;
+    border-radius: var(--xh-separator-radius, var(--xh-shape-pill));
+    background: var(--xh-_separator-paint);
+  }
+
+  [data-scope='separator'][data-part='line'][data-orientation='horizontal'] {
+    block-size: var(--xh-separator-thickness, var(--xh-stroke-thin));
+  }
+
+  [data-scope='separator'][data-part='line'][data-orientation='vertical'] {
+    inline-size: var(--xh-separator-thickness, var(--xh-stroke-thin));
+  }
+
+  /* 分节文字：不参与等分，也不折行 */
+  [data-scope='separator'][data-part='content'] {
+    flex: none;
+    color: var(--xh-separator-content-fg, var(--xh-fg-muted));
+    font-size: var(--xh-separator-content-font-size, var(--xh-text-secondary-size));
+    line-height: var(--xh-leading-normal);
+    white-space: nowrap;
+  }
+
+  /* 文字靠边：靠哪边就把那一侧的线收成一小截，另一侧照旧等分 */
+  [data-scope='separator'][data-part='root'][data-align='start'] > [data-part='line']:first-child,
+  [data-scope='separator'][data-part='root'][data-align='end'] > [data-part='line']:last-child {
+    flex: 0 0 var(--xh-separator-align-length, var(--xh-space-6));
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  [data-scope='separator'][data-part='root'][hidden] {
+    display: none;
+  }
 }

package/css/side-nav.css

@@ -1,30 +1,13 @@
-@layer xihan.motion {
-  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
-     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
-  @keyframes xh-pop-in {
-    from {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
-
-    to {
-      opacity: 1;
-      scale: 1;
-    }
-  }
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
 
-  @keyframes xh-pop-out {
-    from {
-      opacity: 1;
-      scale: 1;
-    }
+/* 定义 side nav 样式。 */
 
-    to {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
-  }
-}
+/* 共享关键帧由 family/motion.css 提供，行走 Collection Item 家族；本皮肤 @import 它们，单独引入仍成立。 */
+@import '../family/collection-item.css';
+@import '../family/motion.css';
 
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
@@ -32,10 +15,41 @@
     --xh-side-nav-skin: 1;
   }
 
-  [data-scope='side-nav'][data-part='root'] {
-    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
-    --xh-icon-size: var(--xh-side-nav-icon-size, var(--xh-glyph-size-text));
+  /* 私有槽同时声明在根与定位层上：折叠态的弹出面板被搬到 portal 落点，
+     不是根的后代，继承不过去。面板里的行与栏内那些消费的是同一批槽 */
+  [data-scope='side-nav']:is([data-part='root'], [data-part='positioner']) {
+    /* 行外的字形按档取尺，缺省 md，随 data-size 换档并同样声明在定位层上（弹出面板里的行也拿得到）；
+       行内的由家族随 data-xh-collection-size 下发（§6.5）。这支只管作者放进行里的图标：
+       侧栏自绘的状态字形（分支行尾的展开方向 chevron）是指示符，branch-indicator 在自己身上
+       把 --xh-icon-size 改接到 --xh-control-indicator-* 一族的盒尺 */
+    --xh-icon-size: var(--xh-side-nav-icon-size, var(--xh-glyph-size-md));
+
+    /* 尺寸档只换这三个私有槽，行从这两处继承它们，换档不必给每个部件各写一条选择器 */
+    --xh-_side-nav-row-h: var(--xh-control-h-md);
+    --xh-_side-nav-row-px: var(--xh-control-px-md);
+    --xh-_side-nav-row-gap: var(--xh-control-gap-md);
+    --xh-_side-nav-row-font-size: var(--xh-control-font-md);
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面那条里 */
+  [data-scope='side-nav']:is([data-part='root'], [data-part='positioner'])[data-size='sm'] {
+    --xh-icon-size: var(--xh-side-nav-icon-size, var(--xh-glyph-size-sm));
+    --xh-_side-nav-row-h: var(--xh-control-h-sm);
+    --xh-_side-nav-row-px: var(--xh-control-px-sm);
+    --xh-_side-nav-row-gap: var(--xh-control-gap-sm);
+    --xh-_side-nav-row-font-size: var(--xh-control-font-sm);
+  }
+
+  [data-scope='side-nav']:is([data-part='root'], [data-part='positioner'])[data-size='lg'] {
+    --xh-icon-size: var(--xh-side-nav-icon-size, var(--xh-glyph-size-lg));
+    --xh-_side-nav-row-h: var(--xh-control-h-lg);
+    --xh-_side-nav-row-px: var(--xh-control-px-lg);
+    --xh-_side-nav-row-gap: var(--xh-control-gap-lg);
+    --xh-_side-nav-row-font-size: var(--xh-control-font-lg);
+  }
 
+  [data-scope='side-nav'][data-part='root'] {
     inline-size: var(--xh-side-nav-w, 240px);
     display: flex;
     flex-direction: column;
@@ -77,8 +91,9 @@
 
   [data-scope='side-nav'][data-part='group-label'] {
     padding-block: var(--xh-side-nav-group-label-py, var(--xh-space-1));
-    padding-inline: var(--xh-side-nav-group-label-px, var(--xh-control-px-md));
+    padding-inline: var(--xh-side-nav-group-label-px, var(--xh-_side-nav-row-px));
     font-size: var(--xh-text-caption-size);
+    font-weight: var(--xh-text-label-weight);
     color: var(--xh-fg-subtle);
     user-select: none;
   }
@@ -102,55 +117,67 @@
     list-style: none;
   }
 
-  /* —— 行：分支按钮与链接同一副长相 —— */
+  /* —— 行：分支按钮与链接同一副长相 ——
+     两种行都走 Collection Item 的 page 语境（页内持久集合，§7.3）：悬停 / 高亮 / 按下面（白底承载 hover 100 →
+     pressed 200，只换面不缩放）、当前页（品牌淡底 + 淡底前景 + 起始侧 2px 指示条，current+hover 20% /
+     +pressed 28%）、展开路径（与 hover 同档的中性面，不用品牌色、不加粗）与禁用面都由家族按 data-current /
+     data-in-path / aria-disabled 给出。这里只把公开槽映射到桥接槽。
+     布局保持 flex 而不用家族网格：一行里可以并排作者自己的图标与徽标，间距统一由行的 gap 给，
+     家族按槽下发的外边距（--xh-collection-gap）归零；行高由 min-block-size 撑起，家族的块向内衬归零 */
   [data-scope='side-nav'][data-part='branch-trigger'],
   [data-scope='side-nav'][data-part='link'] {
+    --xh-collection-block-padding: 0;
+    --xh-collection-inline-padding: var(--xh-side-nav-link-px, var(--xh-_side-nav-row-px));
+    --xh-collection-gap: 0;
+    --xh-collection-font-size: var(--xh-side-nav-link-font-size, var(--xh-_side-nav-row-font-size));
+    --xh-collection-radius: var(--xh-side-nav-link-radius, var(--xh-shape-control));
+    /* 作者的图标尺槽经桥接槽下发到行，家族缺省按 data-xh-collection-size 取档 */
+    --xh-collection-glyph-size: var(--xh-side-nav-icon-size, var(--xh-_collection-glyph-size));
+    --xh-collection-fg-rest: var(--xh-side-nav-row-fg, currentColor);
+    --xh-collection-fg-hover: var(--xh-side-nav-row-fg, currentColor);
+    --xh-collection-fg-keyboard-highlight: var(--xh-side-nav-row-fg, currentColor);
+    --xh-collection-fg-pressed: var(--xh-side-nav-row-fg, currentColor);
+    --xh-collection-bg-hover: var(--xh-side-nav-row-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-keyboard-highlight: var(--xh-side-nav-row-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-pressed: var(--xh-side-nav-row-bg-pressed, var(--xh-bg-subtle-hover));
+    /* 当前页：公开槽名不变，缺省前景由品牌深字改为淡底前景，字重保持 medium；2px 指示条取品牌色 */
+    --xh-collection-bg-current: var(--xh-side-nav-row-bg-active, var(--xh-bg-brand-subtle));
+    --xh-collection-fg-current: var(--xh-side-nav-row-fg-active, var(--xh-fg-on-brand-subtle));
+    --xh-collection-fg-current-hover: var(--xh-side-nav-row-fg-active, var(--xh-fg-on-brand-subtle));
+    --xh-collection-fg-current-highlight: var(--xh-side-nav-row-fg-active, var(--xh-fg-on-brand-subtle));
+    --xh-collection-fg-current-pressed: var(--xh-side-nav-row-fg-active, var(--xh-fg-on-brand-subtle));
+    --xh-collection-font-weight-current: var(--xh-side-nav-row-font-weight-active, var(--xh-font-weight-medium));
+    --xh-collection-font-weight-current-hover: var(--xh-side-nav-row-font-weight-active, var(--xh-font-weight-medium));
+    --xh-collection-font-weight-current-highlight: var(--xh-side-nav-row-font-weight-active, var(--xh-font-weight-medium));
+    --xh-collection-font-weight-current-pressed: var(--xh-side-nav-row-font-weight-active, var(--xh-font-weight-medium));
+    --xh-collection-indicator-fg-current: var(--xh-side-nav-indicator-color, var(--xh-fg-brand));
+    --xh-collection-indicator-fg-current-hover: var(--xh-side-nav-indicator-color, var(--xh-fg-brand));
+    --xh-collection-indicator-fg-current-highlight: var(--xh-side-nav-indicator-color, var(--xh-fg-brand));
+    --xh-collection-indicator-fg-current-pressed: var(--xh-side-nav-indicator-color, var(--xh-fg-brand));
+    /* 展开路径：中性面，字色缺省由品牌色改回行的常态色 */
+    --xh-collection-bg-open-path: var(--xh-side-nav-row-bg-in-path, var(--xh-bg-subtle));
+    --xh-collection-fg-open-path: var(--xh-side-nav-row-fg-in-path, var(--xh-side-nav-row-fg, currentColor));
+    /* data-highlighted 跟的是连接层记的焦点行（指针点选也会落焦）：只换面，焦点环在 :focus-visible 下再接回 */
+    --xh-collection-outline-keyboard-highlight: transparent;
+    --xh-collection-outline-current-highlight: transparent;
+
     display: flex;
     align-items: center;
-    gap: var(--xh-side-nav-link-gap, var(--xh-control-gap-md));
+    gap: var(--xh-side-nav-link-gap, var(--xh-_side-nav-row-gap));
     inline-size: 100%;
-    min-block-size: var(--xh-control-h-md);
-    padding-inline: var(--xh-side-nav-link-px, var(--xh-control-px-md));
+    min-block-size: var(--xh-side-nav-link-h, var(--xh-_side-nav-row-h));
     border: none;
-    border-radius: var(--xh-side-nav-link-radius, var(--xh-shape-control));
-    background: none;
-    color: inherit;
-    font-size: var(--xh-text-body-size);
     text-align: start;
     text-decoration: none;
-    cursor: pointer;
-  }
-
-  /* 悬停与键盘锚点共用中性灰轻档：锚点只认连接层打的 data-highlighted，不读 :focus */
-  [data-scope='side-nav'][data-part='branch-trigger']:not([data-disabled]):is(:hover, [data-highlighted]),
-  [data-scope='side-nav'][data-part='link']:not([data-disabled]):is(:hover, [data-highlighted]) {
-    background: var(--xh-side-nav-row-bg-hover, var(--xh-bg-subtle));
-  }
-
-  [data-scope='side-nav'][data-part='branch-trigger']:focus-visible,
-  [data-scope='side-nav'][data-part='link']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
-  }
-
-  /* 选中的那条：品牌淡底 + 强调字。
-     守卫与轻档那条同特指度，写在其后才压得住——键盘走到当前页那一行时底色仍是品牌淡底 */
-  [data-scope='side-nav'][data-part='link']:not([data-disabled])[data-current] {
-    background: var(--xh-bg-brand-subtle);
-    /* 淡底上的字走 strong 档：fg-brand（600）压在 brand-subtle（100）上只有 4.21 */
-    color: var(--xh-fg-brand-strong);
-    font-weight: var(--xh-font-weight-medium);
   }
 
-  /* 选中项的祖先枝：只染字色，一路指到当前页 */
-  [data-scope='side-nav'][data-part='branch-trigger'][data-in-path] {
-    color: var(--xh-fg-brand);
-  }
+  /* 键盘焦点出现时环才接回并立即到位，不压在背景过渡的中间帧上 */
+  [data-scope='side-nav'][data-part='branch-trigger']:focus-visible:not(:hover),
+  [data-scope='side-nav'][data-part='link']:focus-visible:not(:hover) {
+    --xh-collection-outline-keyboard-highlight: var(--xh-ring-focus);
+    --xh-collection-outline-current-highlight: var(--xh-ring-focus);
 
-  [data-scope='side-nav'][data-part='branch-trigger'][data-disabled],
-  [data-scope='side-nav'][data-part='link'][data-disabled] {
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
+    transition: none;
   }
 
   [data-scope='side-nav'][data-part='branch-text'],
@@ -187,8 +214,9 @@
 
   [data-scope='side-nav'][data-part='root'][data-collapsed] [data-part='branch-trigger']:not([data-popout] *),
   [data-scope='side-nav'][data-part='root'][data-collapsed] [data-part='link']:not([data-popout] *) {
+    --xh-collection-inline-padding: 0;
+
     justify-content: center;
-    padding-inline: 0;
   }
 
   /* 弹出面板的定位层：坐标由连接层写在行内样式上，这里只管层号与命中区。
@@ -198,9 +226,12 @@
     /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，面板继承它限高；
        引擎没算（尚未落位 / 无引擎 / 贴边归零）时不额外限高 */
     --xh-_side-nav-available-h: 100vh;
+    /* 落定那一侧的可用宽度，同样由定位引擎经内联自定义属性写进来，行内轴据此夹取；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时退到视口宽 */
+    --xh-_side-nav-available-w: 100vw;
 
     position: fixed;
-    z-index: var(--xh-side-nav-popout-layer, var(--xh-layer-popover));
+    z-index: var(--xh-side-nav-popout-layer, var(--xh-_layer, var(--xh-layer-popover)));
     pointer-events: auto;
   }
 
@@ -213,20 +244,25 @@
      面板自己不吃子层缩进（padding 整圈盖掉），面板内的嵌套子层照常缩进 */
   [data-scope='side-nav'][data-part='branch-content'][data-popout] {
     min-inline-size: var(--xh-side-nav-popout-min-w, var(--xh-overlay-menu-min-w));
-    max-inline-size: var(--xh-side-nav-popout-max-w, var(--xh-overlay-max-w));
+    /* 静态档与落位后的可用宽度取小：窄视口下面板伸出去，最右侧的内容就点不到了 */
+    max-inline-size: min(var(--xh-side-nav-popout-max-w, var(--xh-overlay-max-w)), var(--xh-_side-nav-available-w));
     padding: var(--xh-side-nav-popout-p, var(--xh-space-1));
     border: var(--xh-stroke-thin) solid var(--xh-side-nav-popout-border, var(--xh-border-default));
-    border-radius: var(--xh-side-nav-popout-radius, var(--xh-shape-surface));
+    border-radius: var(--xh-side-nav-popout-radius, var(--xh-shape-overlay));
     background: var(--xh-side-nav-popout-bg, var(--xh-bg-surface));
     box-shadow: var(--xh-side-nav-popout-shadow, var(--xh-elevation-floating));
 
-    /* 子导航条目数没有上限，矮视口下不限高就整块伸出视口且滚不到 */
+    /* 子导航条目数没有上限，矮视口下不限高就整块伸出视口且滚不到。
+       浮层滚动面：到底后不把滚动链穿透给页面（§6.6）；细条由 reset 层给 */
     max-block-size: min(var(--xh-side-nav-popout-max-h, var(--xh-overlay-menu-max-h)), var(--xh-_side-nav-available-h));
     overflow-y: auto;
+    overscroll-behavior: contain;
   }
 
+  /* 在场那一档才提前备好合成层：属性随 data-state 一起消失，收起后不长期占着 */
   [data-scope='side-nav'][data-part='branch-content'][data-popout][data-state='open'] {
-    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    will-change: opacity, scale;
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
   }
 
   /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
@@ -235,18 +271,30 @@
     animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
+  /* 箭头是行尾的后缀：auto 外边距把它顶到行尾，家族按 suffix 槽下发的外边距已在行上归零。
+     盒里的 chevron 是指示符（§6.5）：盒按指示符档定尺（comfortable 16 / compact 14，与 Tree / TreeSelect
+     的 branch-indicator 同款定尺盒），--xh-icon-size 在自己身上改接到盒的尺，兜底字形与作者塞进盒里的
+     XhIcon 读同一把尺、与盒同边长；不读家族按档下发到行的 --xh-icon-size——那支只管作者放进行里的
+     图标，按图标档取的 20px 比指示符档大一圈。盒自己定尺而不随字形撑开：转 90° 时才不抖 */
   [data-scope='side-nav'][data-part='branch-indicator'] {
+    --xh-icon-size: var(--xh-side-nav-branch-indicator-size, var(--xh-control-indicator-size));
+
     margin-inline-start: auto;
     display: inline-flex;
     flex: none;
-    transition: rotate var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-side-nav-branch-indicator-size, var(--xh-control-indicator-size));
+    block-size: var(--xh-side-nav-branch-indicator-size, var(--xh-control-indicator-size));
+    transition: rotate var(--xh-motion-duration-micro) var(--xh-motion-ease-enter-strong);
   }
 
   [data-scope='side-nav'][data-part='branch-indicator'][data-state='open'] {
     rotate: 90deg;
   }
 
-  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中。
+     尺寸读部件自己改接过的 --xh-icon-size：chevron 与盒同边长（见上面那块） */
   [data-scope='side-nav'][data-part='branch-indicator']:empty::before {
     content: '';
     display: inline-block;
@@ -261,11 +309,21 @@
   /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
      写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
   [data-scope='side-nav'][data-part='root'][hidden],
+  [data-scope='side-nav'][data-part='list'][hidden],
   [data-scope='side-nav'][data-part='group'][hidden],
   [data-scope='side-nav'][data-part='branch'][hidden],
+  [data-scope='side-nav'][data-part='branch-trigger'][hidden],
   [data-scope='side-nav'][data-part='item'][hidden],
   [data-scope='side-nav'][data-part='link'][hidden],
   [data-scope='side-nav'][data-part='branch-indicator'][hidden] {
     display: none;
   }
+
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    [data-scope='side-nav'][data-part='positioner'] {
+      display: none;
+    }
+  }
 }

package/css/signature-pad.css

@@ -1,3 +1,12 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 signature pad 样式。 */
+
+@import '../family/action-control.css';
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='signature-pad'] {
@@ -10,37 +19,49 @@
     position: relative;
     display: flex;
     flex-direction: column;
-    gap: var(--xh-signature-pad-gap, var(--xh-stack-gap-md));
+    /* 画布到清空按钮与状态句的距离；标签到画布另有一档，见 label */
+    gap: var(--xh-signature-pad-gap, var(--xh-space-2));
   }
 
+  /* 复合单字段的标签（§6.4）：14 / 500 / fg-default，不随档；贴画布 space-1——
+     容器的 gap 归画布之后的部件，标签在它之上补一段差值把距离收成目标值 */
   [data-scope='signature-pad'][data-part='label'] {
-    color: var(--xh-signature-pad-label-fg, var(--xh-fg-muted));
+    margin-block-end: calc(
+      var(--xh-signature-pad-label-gap, var(--xh-space-1))
+      - var(--xh-signature-pad-gap, var(--xh-space-2))
+    );
+    color: var(--xh-signature-pad-label-fg, var(--xh-fg-default));
     font-size: var(--xh-signature-pad-label-font-size, var(--xh-text-label-size));
     font-weight: var(--xh-signature-pad-label-font-weight, var(--xh-text-label-weight));
-    line-height: var(--xh-leading-none);
   }
 
   [data-scope='signature-pad'][data-part='label'][data-disabled] {
-    color: var(--xh-fg-subtle);
+    color: var(--xh-signature-pad-label-fg-disabled, var(--xh-fg-subtle));
   }
 
   /* 画布是块状的写字区：宽度铺满外层，高度由宽高比决定。
      控件行高那把尺量的是一行控件，一块要写字的面积用不上它。
-     touch-action 由连接层内联写死，触摸落笔才不会被页面滚动抢走。 */
+     touch-action 由连接层内联写死，触摸落笔才不会被页面滚动抢走。
+     外壳按字段规则自绘（§8.3 登记的画布型字段例外：字段家族配方钉死控件行高，画布按宽高比撑高吃不下它）：
+     静息透明底 + border-control 描边 + control 圆角 + 无影 */
   [data-scope='signature-pad'][data-part='control'] {
     display: block;
     inline-size: 100%;
     aspect-ratio: var(--xh-signature-pad-aspect-ratio, 5 / 2);
     border: var(--xh-stroke-thin) solid var(--xh-signature-pad-border, var(--xh-border-control));
-    border-radius: var(--xh-signature-pad-radius, var(--xh-shape-surface));
-    background: var(--xh-signature-pad-bg, var(--xh-bg-surface));
+    border-radius: var(--xh-signature-pad-radius, var(--xh-shape-control));
+    background: var(--xh-signature-pad-bg, transparent);
     cursor: crosshair;
     /* 一划就会把画布连同旁边的文字一起刷成选中态 */
     user-select: none;
+    /* 落笔、校验不过与禁用三档各换一次描边或底色，换的过程要看得出来 */
+    transition:
+      border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   [data-scope='signature-pad'][data-part='control'][data-invalid] {
-    border-color: var(--xh-border-invalid);
+    border-color: var(--xh-signature-pad-control-border-invalid, var(--xh-border-invalid));
   }
 
   /* 落笔期间把描边压深一档。border-strong 是装饰梯度里的一档，比 border-control 更淡，
@@ -49,13 +70,17 @@
     border-color: var(--xh-signature-pad-border-drawing, var(--xh-border-control-hover));
   }
 
-  /* 只读仍看得见签名，只是改不动：收掉手型，别暗示"在这儿能写" */
-  [data-scope='signature-pad'][data-part='control'][data-readonly] {
+  /* 只读仍看得见签名，只是改不动：收掉手型，别暗示"在这儿能写"；
+     面按字段只读规则只换到淡底，描边不动（§7.2 第 9 条） */
+  [data-scope='signature-pad'][data-part='control'][data-readonly]:not([data-disabled]) {
+    background: var(--xh-signature-pad-bg-readonly, var(--xh-bg-subtle));
     cursor: default;
   }
 
+  /* 字段禁用面（§7.2 第 9 条）：描边退到 border-default、底换淡底 */
   [data-scope='signature-pad'][data-part='control'][data-disabled] {
-    background: var(--xh-signature-pad-bg-disabled, var(--xh-bg-muted));
+    border-color: var(--xh-signature-pad-border-disabled, var(--xh-border-default));
+    background: var(--xh-signature-pad-bg-disabled, var(--xh-bg-subtle));
     cursor: not-allowed;
   }
 
@@ -69,64 +94,59 @@
 
   /* 笔迹是一条填充路径（每一笔是它的一条子路径），不是描边：
      粗细要随压感变，而 stroke-width 全线只有一个值 */
-  [data-scope='signature-pad'][data-part='segment'] {
+  [data-scope='signature-pad'][data-part='path'] {
     fill: var(--xh-signature-pad-ink, var(--xh-fg-default));
     stroke: none;
   }
 
+  /*
+   * 清空按钮是画布旁的独立文字按钮（§9.1）：盒型、sm 档几何、outline 四态面、0.97 按压与粗指针命中区由家族配方
+   * 按连接层投影的 data-xh-action-variant / -size 给出（缺省 outline，白底承载阶梯 100 → 200）。这里只把公开槽
+   * 桥接到矩阵之前（使用者槽 → 形态矩阵 → 家族缺省）与几何槽映射，矩阵各态无影（§8.3 淡底与阴影互斥）。
+   */
   [data-scope='signature-pad'][data-part='clear-trigger'] {
-    display: inline-flex;
+    --xh-action-bg-rest: var(--xh-signature-pad-clear-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-signature-pad-clear-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-signature-pad-clear-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-bg-focus-visible: var(--xh-signature-pad-clear-bg, var(--xh-_action-variant-bg-focus-visible));
+    --xh-action-bg-disabled: var(--xh-signature-pad-clear-bg-disabled, var(--xh-_action-variant-bg-disabled));
+    --xh-action-fg-rest: var(--xh-signature-pad-clear-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-signature-pad-clear-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-signature-pad-clear-fg, var(--xh-_action-variant-fg-pressed));
+    --xh-action-fg-focus-visible: var(--xh-signature-pad-clear-fg, var(--xh-_action-variant-fg-focus-visible));
+    --xh-action-border-rest: var(--xh-signature-pad-clear-border, var(--xh-_action-variant-border-rest));
+    --xh-action-border-hover: var(--xh-signature-pad-clear-border-hover, var(--xh-_action-variant-border-hover));
+    --xh-action-border-pressed: var(--xh-signature-pad-clear-border-hover, var(--xh-_action-variant-border-pressed));
+    --xh-action-border-focus-visible: var(--xh-signature-pad-clear-border, var(--xh-_action-variant-border-focus-visible));
+    /* 矩阵各态无影：悬停不再抬影（raised 只给 Button），使用者槽仍可自行加 */
+    --xh-action-shadow-hover: var(--xh-signature-pad-clear-shadow-hover, none);
+    --xh-action-radius: var(--xh-signature-pad-clear-radius, var(--xh-shape-control));
+    --xh-action-visual-size: var(--xh-signature-pad-clear-h, var(--xh-_action-profile-visual-size));
+    --xh-action-padding-inline: var(--xh-signature-pad-clear-px, var(--xh-_action-profile-padding-inline));
+    --xh-action-gap: var(--xh-signature-pad-clear-gap, var(--xh-_action-profile-gap));
+    --xh-action-font-size: var(--xh-signature-pad-clear-font-size, var(--xh-_action-profile-font-size));
+    /* 作者塞进来的图标随档取字形尺（sm = 16px） */
+    --xh-icon-size: var(--xh-signature-pad-clear-icon-size, var(--xh-_action-profile-glyph-size));
+
+    /* 竖排容器里不铺满一行：按钮只占自己的宽 */
     align-self: flex-start;
-    align-items: center;
-    justify-content: center;
-    gap: var(--xh-signature-pad-clear-gap, var(--xh-control-gap-sm));
-    block-size: var(--xh-signature-pad-clear-h, var(--xh-control-h-sm));
-    padding-inline: var(--xh-signature-pad-clear-px, var(--xh-control-px-sm));
-    border: var(--xh-stroke-thin) solid var(--xh-signature-pad-clear-border, var(--xh-border-control));
-    border-radius: var(--xh-signature-pad-clear-radius, var(--xh-shape-control));
-    background: var(--xh-signature-pad-clear-bg, var(--xh-bg-surface));
-    color: var(--xh-signature-pad-clear-fg, var(--xh-fg-default));
-    font-size: var(--xh-text-label-size);
-    line-height: var(--xh-leading-none);
-    cursor: pointer;
-    transition:
-      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
-      scale var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
-  }
-
-  [data-scope='signature-pad'][data-part='clear-trigger']:hover {
-    background: var(--xh-signature-pad-clear-bg-hover, var(--xh-bg-subtle-hover));
-  }
-
-  /* 按下：换到按压档底色并轻微下压，松手弹回；禁用钮不压 */
-  [data-scope='signature-pad'][data-part='clear-trigger']:not(:disabled):active {
-    background: var(--xh-signature-pad-clear-bg-active, var(--xh-bg-subtle-active));
-    scale: var(--xh-motion-scale-press);
   }
 
-  [data-scope='signature-pad'][data-part='clear-trigger']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
-  }
-
-  /* 空画布时按钮照常可按（收起它会让焦点掉回 body），只把它压淡一档 */
+  /* 空画布时按钮照常可按（收起它会让焦点掉回 body），只把静息前景压淡一档；悬停与按下仍回到默认前景 */
   [data-scope='signature-pad'][data-part='clear-trigger'][data-empty] {
-    color: var(--xh-fg-muted);
+    --xh-action-fg-rest: var(--xh-signature-pad-clear-fg-empty, var(--xh-fg-muted));
   }
 
-  /* 单体原生控件走 :disabled；集合条目那套 [data-disabled] 在这里命不中。
-     禁用只换前景色，不再叠 opacity——两样一起上会把文字压到看不见 */
-  [data-scope='signature-pad'][data-part='clear-trigger']:disabled {
-    background: var(--xh-signature-pad-clear-bg-disabled, var(--xh-bg-muted));
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
+  /* 面是实心的，环色与面同族，画在面里就看不出来；环改取面自己的前景色 */
+  [data-scope='signature-pad'][data-part='clear-trigger'][data-xh-action-variant='solid']:focus-visible {
+    --xh-action-ring-color-focus-visible: currentColor;
   }
 
-  /* 签没签的那句话。读屏靠它播报，看得见的人也用得上，因此不做视觉隐藏 */
+  /* 签没签的那句话是说明角色（§6.4）：13 / fg-muted / leading-normal。读屏靠它播报，看得见的人也用得上，因此不做视觉隐藏 */
   [data-scope='signature-pad'][data-part='status'] {
     color: var(--xh-signature-pad-status-fg, var(--xh-fg-muted));
-    font-size: var(--xh-signature-pad-status-font-size, var(--xh-text-label-size));
-    line-height: var(--xh-leading-none);
+    font-size: var(--xh-signature-pad-status-font-size, var(--xh-text-secondary-size));
+    line-height: var(--xh-leading-normal);
   }
 
   /* 表单影子的视觉隐藏（绝对定位 + 1px + clip-path）连接层内联给全了，这里不重复也不覆盖，