@xihan-ui/styles 1.0.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# @xihan-ui/styles
+
+## 1.0.0-alpha.0
+
+### Major Changes
+
+- bc65cb7: 首个公开版本：框架无关的 UI 基座。
+
+  自研薄 FSM 内核 + headless（anatomy / machine / connect）+ 设计令牌与主题运行时 + 样式层，
+  102 个组件在 Vue 与 Web Components 两套适配器上共用同一份内核，跨适配器一致性套件与
+  真实 Chromium 里的无障碍扫描、浮层定位契约全绿。
+
+  浮层定位、虚拟滚动、Web Components 响应式基类、代码着色、流式 Markdown 均为自研，
+  运行时不带第三方依赖。
+
+- 84b1aa3: 新增 Icon 原语，`@xihan-ui/icons` 整包重写为首方图标集。
+
+  旧的 `@xihan-ui/icons` 是 27 个第三方图标集的聚合（约四万个图标），已整体移除并在
+  npm 上弃用。新包只收自研图标，第一批 29 个覆盖组件库自用的全部语义，24×24 单色
+  描边、`stroke-width` 2。
+
+  用法：
+
+  - `@xihan-ui/kernel` 导出 `IconRecord` / `IconNode` / `IconTag` 三个类型
+  - `@xihan-ui/headless` 导出 `connectIcon` / `iconAnatomy` / `iconMeta` / `iconKeyboard`
+  - `@xihan-ui/vue` 导出 `XhIcon`，`@xihan-ui/web-components` 注册 `<xh-icon>`
+  - `@xihan-ui/styles` 新增 `icon.css`，`data-size` 与 `data-weight` 各三档
+
+  图标记录是结构化节点数组而不是 SVG 字符串，渲染端逐节点建元素，运行期不经 HTML
+  解析器。图标数据传的是记录本身而不是名字：按名字查表要把全表静态引进来，摇树会
+  整个失效。
+
+  WC 侧要在 `<svg data-xh-part="root">` 里留一个空的 `<g data-xh-part="glyph"></g>`
+  作为授权点，元素只在它内部铺图元；不留这个空壳就一个节点都不动，手写内联 SVG 与
+  `<use>` 引用两种写法因此都还能用。`icon` 是对象，只能走 property 传，属性里写不出来。
+
+  可及名字两态互斥：`label` 给了非空白文本就输出 `role="img"` 与 `aria-label`，否则
+  输出 `aria-hidden="true"`。只有图标的按钮请把名字写在按钮上而不是图标上，两处都写
+  读屏会念两遍。
+
+### Patch Changes
+
+- Updated dependencies [bc65cb7]
+  - @xihan-ui/tokens@1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-Present XiHanFun and contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @xihan-ui/styles
+
+默认皮肤：108 份纯 CSS，零 JS。只按 `[data-scope][data-part]` 与 `data-*` 选中，不匹配标签名也不匹配 class——所以整套换掉它不影响任何行为。
+
+**谁会装它**：不想自己写样式的人装它。要做自己的设计语言，就不装，照解剖文档写一套自己的。
+
+## 用法
+
+```ts
+/* 全量 */
+import '@xihan-ui/styles'
+
+/* 或按需：令牌与层序先行，tone 决定语气轴，缺了它 tone 会静默回落品牌色 */
+import '@xihan-ui/styles/layers.css'
+import '@xihan-ui/styles/tone.css'
+import '@xihan-ui/styles/button.css'
+```
+
+## 装
+
+```bash
+pnpm add @xihan-ui/styles
+```
+
+完整文档见 [https://ui.docs.xihanfun.com](https://ui.docs.xihanfun.com)。这个包属于 `design/` 组，组的含义见仓库里的 `ui/packages/README.md`。
+
+许可：MIT

package/css/accordion.css

@@ -0,0 +1,108 @@
+@layer xihan.components {
+  [data-scope='accordion'][data-part='root'] {
+    /* 尺寸档只换这四个私有槽，标题栏从 root 继承它们，换档不必给每个部件各写一条选择器 */
+    --xh-_accordion-trigger-h: var(--xh-control-h-md);
+    --xh-_accordion-trigger-px: var(--xh-control-px-md);
+    --xh-_accordion-trigger-gap: var(--xh-control-gap-md);
+    --xh-_accordion-trigger-font-size: var(--xh-text-label-size);
+
+    /* 语气落在展开着的标题上，指示器写在标题里、跟着继承这个色，不另立规则。
+       没写 data-tone 时 --xh-_tone-fg 没被声明，退回原来的前景色。
+       聚焦环不在其列，它恒是 --xh-ring-focus */
+    --xh-_accordion-open-fg: var(--xh-_tone-fg, var(--xh-fg-default));
+
+    display: flex;
+    flex-direction: column;
+    inline-size: 100%;
+  }
+
+  [data-scope='accordion'][data-part='root'][data-orientation='horizontal'] {
+    flex-direction: row;
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  [data-scope='accordion'][data-part='root'][data-size='sm'] {
+    --xh-_accordion-trigger-h: var(--xh-control-h-sm);
+    --xh-_accordion-trigger-px: var(--xh-control-px-sm);
+    --xh-_accordion-trigger-gap: var(--xh-control-gap-sm);
+    --xh-_accordion-trigger-font-size: var(--xh-font-size-sm);
+  }
+
+  [data-scope='accordion'][data-part='root'][data-size='lg'] {
+    --xh-_accordion-trigger-h: var(--xh-control-h-lg);
+    --xh-_accordion-trigger-px: var(--xh-control-px-lg);
+    --xh-_accordion-trigger-gap: var(--xh-control-gap-lg);
+    --xh-_accordion-trigger-font-size: var(--xh-font-size-lg);
+  }
+
+  [data-scope='accordion'][data-part='item'] {
+    border-block-end: 1px solid var(--xh-accordion-item-border, var(--xh-border-default));
+    min-inline-size: 0;
+  }
+
+  [data-scope='accordion'][data-part='header'] {
+    margin: 0;
+    font: inherit;
+  }
+
+  [data-scope='accordion'][data-part='trigger'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: space-between;
+    inline-size: 100%;
+    gap: var(--xh-accordion-trigger-gap, var(--xh-_accordion-trigger-gap));
+    block-size: var(--xh-accordion-trigger-h, var(--xh-_accordion-trigger-h));
+    padding-inline: var(--xh-accordion-trigger-px, var(--xh-_accordion-trigger-px));
+    border: 0;
+    border-radius: var(--xh-accordion-trigger-radius, var(--xh-shape-control));
+    background: var(--xh-accordion-trigger-bg, transparent);
+    color: var(--xh-accordion-trigger-fg, var(--xh-fg-default));
+    font-size: var(--xh-accordion-trigger-font-size, var(--xh-_accordion-trigger-font-size));
+    font-weight: var(--xh-accordion-trigger-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-none);
+    cursor: pointer;
+  }
+
+  [data-scope='accordion'][data-part='trigger']:hover {
+    background: var(--xh-accordion-trigger-bg-hover, var(--xh-bg-subtle));
+  }
+
+  [data-scope='accordion'][data-part='trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  [data-scope='accordion'][data-part='trigger'][data-state='open'] {
+    color: var(--xh-accordion-trigger-fg, var(--xh-_accordion-open-fg));
+  }
+
+  /* 禁用条目走 aria-disabled，仍留在 Tab 序里，只是不可操作 */
+  [data-scope='accordion'][data-part='trigger'][data-disabled] {
+    cursor: not-allowed;
+    opacity: var(--xh-state-disabled-opacity);
+  }
+
+  [data-scope='accordion'][data-part='indicator'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: none;
+    line-height: var(--xh-leading-none);
+    transition: rotate var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='accordion'][data-part='indicator']::before {
+    content: '⌄';
+  }
+
+  [data-scope='accordion'][data-part='indicator'][data-state='open'] {
+    rotate: 180deg;
+  }
+
+  [data-scope='accordion'][data-part='content'] {
+    padding-block: var(--xh-accordion-content-py, var(--xh-stack-gap-md));
+    padding-inline: var(--xh-accordion-content-px, var(--xh-control-px-md));
+    color: var(--xh-accordion-content-fg, var(--xh-fg-default));
+  }
+}

package/css/affix.css

@@ -0,0 +1,27 @@
+@layer xihan.components {
+  /* 占位盒就是 content 在常规流里占的那块地方。
+     这里不声明 display，也不写高度：吸住时冻结的高度由连接层量好写进内联样式（它量得到，样式表量不到），
+     没吸住时高度就该跟着内容走。不给 display，UA 的 [hidden]{display:none} 也仍然压得住 */
+  [data-scope='affix'][data-part='root'] {
+    /* 脱流后 content 不再撑开占位盒，宽度改从父级取 */
+    inline-size: 100%;
+  }
+
+  /* 没吸住时是常规流里普通的一块，不做任何定位 */
+  [data-scope='affix'][data-part='content'] {
+    inline-size: 100%;
+  }
+
+  /*
+   * 吸住：脱离常规流钉在视口上。
+   * 四个落位数（top / bottom / left / width）由连接层写成内联样式——它们是照占位盒的矩形实测出来的
+   * 物理量，换成逻辑属性会在 RTL 下贴反。这里只管「用哪种定位、压在第几层」。
+   * 另一件必须提防的事：fixed 认的是视口，祖先上一旦出现
+   * transform / filter / backdrop-filter / contain，包含块就被抢走，钉住的内容立刻贴错位置——
+   * 所以别往覆盖钩子里加这几个属性。
+   */
+  [data-scope='affix'][data-part='content'][data-affixed] {
+    position: fixed;
+    z-index: var(--xh-affix-layer, var(--xh-layer-sticky));
+  }
+}

package/css/alert.css

@@ -0,0 +1,108 @@
+@layer xihan.components {
+  [data-scope='alert'][data-part='root'] {
+    /* 强调色随语气走，底色/描边/图标色都由它推导出来，换语气不必逐条属性各写一遍。
+       没写 data-tone 时 --xh-_tone 没被声明，退回原来的 info 蓝 */
+    --xh-_alert-accent: var(--xh-_tone-soft, var(--xh-color-info-500));
+    /* 底色与描边由语气色兑进当前表面色得到：表面色本身跟着深浅模式翻，
+       兑出来的淡底也就跟着翻，不必为深色再写一套选择器 */
+    --xh-_alert-tint: color-mix(in oklab, var(--xh-_alert-accent) 12%, var(--xh-bg-surface));
+    --xh-_alert-edge: color-mix(in oklab, var(--xh-_alert-accent) 32%, var(--xh-bg-surface));
+
+    display: flex;
+    /* 说明用 flex: 1 1 100% 独占一行，容器不换行的话它只会挤在标题旁边 */
+    flex-wrap: wrap;
+    align-items: flex-start;
+    gap: var(--xh-alert-gap, var(--xh-space-3));
+    padding-block: var(--xh-alert-py, var(--xh-space-3));
+    padding-inline: var(--xh-alert-px, var(--xh-space-4));
+    border: var(--xh-stroke-thin) solid var(--xh-alert-border, var(--xh-_alert-edge));
+    border-radius: var(--xh-alert-radius, var(--xh-shape-surface));
+    background: var(--xh-alert-bg, var(--xh-_alert-tint));
+    color: var(--xh-alert-fg, var(--xh-fg-default));
+    font-size: var(--xh-alert-font-size, var(--xh-font-size-md));
+    line-height: var(--xh-alert-leading, var(--xh-leading-normal));
+  }
+
+  /* 收起态连接层给的是 hidden 属性，而上面声明了 display——
+     漏掉这条，关掉的提示还会一直摊在页面上 */
+  [data-scope='alert'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  [data-scope='alert'][data-part='icon'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: none;
+    /* 与首行文字对齐：图标框高取一行正文的行高 */
+    block-size: calc(var(--xh-font-size-md) * var(--xh-leading-normal));
+    inline-size: var(--xh-alert-icon-size, var(--xh-control-indicator-size));
+    color: var(--xh-alert-icon-fg, var(--xh-_alert-accent));
+  }
+
+  /* 标题与说明摞成一列，占满 root 剩下的横向空间，
+     关闭按钮才推得到行尾 */
+  [data-scope='alert'][data-part='title'],
+  [data-scope='alert'][data-part='description'] {
+    margin: 0;
+    min-inline-size: 0;
+  }
+
+  [data-scope='alert'][data-part='title'] {
+    flex: 1 1 auto;
+    color: var(--xh-alert-title-fg, var(--xh-fg-default));
+    font-size: var(--xh-alert-title-font-size, var(--xh-font-size-md));
+    font-weight: var(--xh-alert-title-font-weight, var(--xh-font-weight-semibold));
+    line-height: var(--xh-alert-title-leading, var(--xh-leading-tight));
+  }
+
+  [data-scope='alert'][data-part='description'] {
+    flex: 1 1 100%;
+    color: var(--xh-alert-description-fg, var(--xh-fg-muted));
+    font-size: var(--xh-alert-description-font-size, var(--xh-font-size-sm));
+  }
+
+  /* 没写标题时说明自己占满这一行，否则它会挤在标题旁边 */
+  [data-scope='alert'][data-part='title']:empty {
+    display: none;
+  }
+
+  [data-scope='alert'][data-part='close-trigger'] {
+    flex: none;
+    /* 前面没有标题时也把叉推到行尾 */
+    margin-inline-start: auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    block-size: var(--xh-alert-close-size, var(--xh-control-h-sm));
+    inline-size: var(--xh-alert-close-size, var(--xh-control-h-sm));
+    border: 0;
+    border-radius: var(--xh-alert-close-radius, var(--xh-shape-control));
+    background: transparent;
+    color: var(--xh-alert-close-fg, var(--xh-fg-muted));
+    /* 按钮不继承字族字号，不接回来的话提示里会突然冒出一段系统 UI 字体 */
+    font: inherit;
+    line-height: var(--xh-leading-none);
+    cursor: pointer;
+  }
+
+  /* closable=false 时连接层同时给了 hidden 与 disabled，这条是它真正收起的那一半 */
+  [data-scope='alert'][data-part='close-trigger'][hidden] {
+    display: none;
+  }
+
+  [data-scope='alert'][data-part='close-trigger']:hover:not(:disabled) {
+    background: color-mix(in oklab, var(--xh-_alert-accent) 16%, transparent);
+    color: var(--xh-alert-close-fg-hover, var(--xh-fg-default));
+  }
+
+  [data-scope='alert'][data-part='close-trigger']:disabled {
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  [data-scope='alert'][data-part='close-trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+}

package/css/anchor.css

@@ -0,0 +1,137 @@
+@layer xihan.components {
+  /* 根节点是 nav 地标，不参与排版：整条目录的布局全在 list 上，
+     这里不给 display，UA 的 [hidden]{display:none} 就仍然压得住 */
+  [data-scope='anchor'][data-part='root'] {
+    /* 尺寸档只换这两个私有槽，链接从 root 继承它们，换档不必给每个部件各写一条选择器 */
+    --xh-_anchor-font-size: var(--xh-text-label-size);
+    --xh-_anchor-link-px: var(--xh-space-3);
+    /* 当前那一节的指示条与文字随语气走。没写 data-tone 时这两个槽都没被声明，退回原来的品牌色。
+       指示条是装饰性的色条，取柔和档；文字要压在普通背景上读，取语气的文字档。
+       聚焦环不在其列，它恒是 --xh-ring-focus */
+    --xh-_anchor-accent: var(--xh-_tone-soft, var(--xh-fg-brand));
+    --xh-_anchor-accent-text: var(--xh-_tone-fg, var(--xh-fg-brand));
+
+    color: var(--xh-anchor-fg, var(--xh-fg-muted));
+    font-size: var(--xh-anchor-font-size, var(--xh-_anchor-font-size));
+    line-height: var(--xh-anchor-leading, var(--xh-leading-normal));
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里；链接的内边距走控件内边距那把尺，缺省的 --xh-space-3 即它的中档 */
+  [data-scope='anchor'][data-part='root'][data-size='sm'] {
+    --xh-_anchor-font-size: var(--xh-font-size-sm);
+    --xh-_anchor-link-px: var(--xh-control-px-sm);
+  }
+
+  [data-scope='anchor'][data-part='root'][data-size='lg'] {
+    --xh-_anchor-font-size: var(--xh-font-size-lg);
+    --xh-_anchor-link-px: var(--xh-control-px-lg);
+  }
+
+  /* 指示条的定位参照系（它是 absolute，量出来的偏移就是相对这里的）。
+     ul 的项目符号与内外边距是 UA 给的，库里没有全局 preflight，只能在这儿自己抹平 */
+  [data-scope='anchor'][data-part='list'] {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-anchor-gap, var(--xh-space-1));
+    margin: 0;
+    padding: 0;
+    /* 起始缘的那条轨道：指示条就在它上面滑 */
+    border-inline-start: var(--xh-stroke-thin) solid var(--xh-anchor-track, var(--xh-border-default));
+    list-style: none;
+  }
+
+  [data-scope='anchor'][data-part='list'][hidden] {
+    display: none;
+  }
+
+  /* 横排：轨道从起始缘挪到底边，条目改成一行 */
+  [data-scope='anchor'][data-part='list'][data-orientation='horizontal'] {
+    flex-direction: row;
+    align-items: center;
+    gap: var(--xh-anchor-gap-horizontal, var(--xh-space-2));
+    border-inline-start: 0;
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-anchor-track, var(--xh-border-default));
+  }
+
+  [data-scope='anchor'][data-part='item'] {
+    display: flex;
+    /* 库里没有全局 preflight，列表项的外边距在这里自己抹平 */
+    margin: 0;
+    /* 允许被压缩，链接内部的省略号才有生效的余地 */
+    min-inline-size: 0;
+  }
+
+  [data-scope='anchor'][data-part='item'][hidden] {
+    display: none;
+  }
+
+  [data-scope='anchor'][data-part='link'] {
+    display: inline-flex;
+    align-items: center;
+    /* 一节的标题可能很长，压不住会把整列撑开 */
+    max-inline-size: var(--xh-anchor-link-max-w, 14rem);
+    padding-block: var(--xh-anchor-link-py, var(--xh-space-1));
+    padding-inline: var(--xh-anchor-link-px, var(--xh-_anchor-link-px));
+    border-radius: var(--xh-anchor-link-radius, var(--xh-shape-control));
+    color: inherit;
+    white-space: nowrap;
+    text-decoration: none;
+    text-overflow: ellipsis;
+    overflow: hidden;
+    transition: color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='anchor'][data-part='link'][hidden] {
+    display: none;
+  }
+
+  [data-scope='anchor'][data-part='link']:hover {
+    color: var(--xh-anchor-link-fg-hover, var(--xh-fg-default));
+  }
+
+  [data-scope='anchor'][data-part='link']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* 当前那一节：颜色与字重都跟着变，不只靠指示条——
+     指示条是可选部件，作者不渲染它时"当前在哪"仍然要看得出来 */
+  [data-scope='anchor'][data-part='link'][data-active] {
+    color: var(--xh-anchor-link-fg-active, var(--xh-_anchor-accent-text));
+    font-weight: var(--xh-anchor-link-font-weight-active, var(--xh-font-weight-medium));
+  }
+
+  /* 主轴上的位置与长度由连接层写成内联样式（它量得到，样式表量不到）；
+     这里只管交叉轴的贴边与粗细，以及长什么样 */
+  [data-scope='anchor'][data-part='indicator'] {
+    position: absolute;
+    display: block;
+    /* 指示条也是列表项，宿主给 li 的外边距会把绝对定位的它推离条目 */
+    margin: 0;
+    inset-inline-start: calc(var(--xh-anchor-indicator-thickness, var(--xh-stroke-thick)) * -1);
+    inline-size: var(--xh-anchor-indicator-thickness, var(--xh-stroke-thick));
+    border-radius: var(--xh-anchor-indicator-radius, var(--xh-radius-full));
+    background: var(--xh-anchor-indicator-color, var(--xh-_anchor-accent));
+    transition:
+      inset-block-start var(--xh-motion-duration-enter) var(--xh-motion-ease-enter),
+      block-size var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* display 会盖掉 hidden 属性的 UA 规则，无激活项时显式让位 */
+  [data-scope='anchor'][data-part='indicator'][hidden] {
+    display: none;
+  }
+
+  /* 横排：指示条改躺在底边的轨道上，交叉轴换成块轴 */
+  [data-scope='anchor'][data-part='indicator'][data-orientation='horizontal'] {
+    inset-inline-start: auto;
+    inset-block-end: calc(var(--xh-anchor-indicator-thickness, var(--xh-stroke-thick)) * -1);
+    inline-size: auto;
+    block-size: var(--xh-anchor-indicator-thickness, var(--xh-stroke-thick));
+    transition:
+      inset-inline-start var(--xh-motion-duration-enter) var(--xh-motion-ease-enter),
+      inline-size var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+}

package/css/avatar-group.css

@@ -0,0 +1,82 @@
+@layer xihan.components {
+  /* 一排叠放的头像：后一枚压在前一枚上。
+     组内共用的直径与字号在容器上写一次，沿继承流给每一枚；自己写了档位的那一枚仍按自己的档走 */
+  [data-scope='avatar-group'][data-part='root'] {
+    /* 私有槽位：整组共用的直径、字号与叠放量，换档只改这三个 */
+    --xh-_avatar-group-size: var(--xh-avatar-group-size, var(--xh-control-h-md));
+    --xh-_avatar-group-font-size: var(--xh-avatar-group-font-size, var(--xh-font-size-sm));
+    --xh-_avatar-group-overlap: var(--xh-avatar-group-overlap, var(--xh-space-2_5));
+
+    /* 流给组内每一枚 */
+    --xh-avatar-size: var(--xh-_avatar-group-size);
+    --xh-avatar-font-size: var(--xh-_avatar-group-font-size);
+
+    display: inline-flex;
+    align-items: center;
+  }
+
+  /* 给了 display 的角色节点必须补这条：display 声明会盖掉 UA 的 [hidden]{display:none}，
+     不补的话作者给节点加 hidden 后它照样显示 */
+  [data-scope='avatar-group'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 尺寸 —— */
+  /* 三档对齐控件档位，缺省档写在上面的基础规则里；
+     字号与叠放量跟着直径一起缩放，小头像里回退字放得下、大头像里压住的那段也按比例长 */
+  [data-scope='avatar-group'][data-part='root'][data-size='sm'] {
+    --xh-_avatar-group-size: var(--xh-avatar-group-size, var(--xh-control-h-sm));
+    --xh-_avatar-group-font-size: var(--xh-avatar-group-font-size, var(--xh-font-size-xs));
+    --xh-_avatar-group-overlap: var(--xh-avatar-group-overlap, var(--xh-space-2));
+  }
+
+  [data-scope='avatar-group'][data-part='root'][data-size='lg'] {
+    --xh-_avatar-group-size: var(--xh-avatar-group-size, var(--xh-control-h-lg));
+    --xh-_avatar-group-font-size: var(--xh-avatar-group-font-size, var(--xh-font-size-md));
+    --xh-_avatar-group-overlap: var(--xh-avatar-group-overlap, var(--xh-space-3));
+  }
+
+  /* —— 叠放 —— */
+  /* 谁压在谁上面得能指定，所以每一枚都是定位元素；
+     再描一圈底色，被压住的那条边才与上一枚分得开 */
+  [data-scope='avatar-group'][data-part='root'] > * {
+    position: relative;
+  }
+
+  [data-scope='avatar-group'][data-part='root'] > *,
+  [data-scope='avatar-group'][data-part='root'] > * [data-scope='avatar'][data-part='root'] {
+    box-shadow: 0 0 0 var(--xh-stroke-thick) var(--xh-avatar-group-ring, var(--xh-bg-surface));
+  }
+
+  /* 后一枚往回挪一段，压在前一枚上 */
+  [data-scope='avatar-group'][data-part='root'] > * + * {
+    margin-inline-start: calc(-1 * var(--xh-_avatar-group-overlap));
+  }
+
+  /* 指到哪一枚，哪一枚整个露出来 */
+  [data-scope='avatar-group'][data-part='root'] > *:hover {
+    z-index: 1;
+  }
+
+  /* —— 溢出计数 —— */
+  /* 「+N」是这一排里的又一枚：直径、形状与字号跟着组走，里面写什么由作者定 */
+  [data-scope='avatar-group'][data-part='overflow'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-_avatar-group-size);
+    block-size: var(--xh-_avatar-group-size);
+    border-radius: var(--xh-avatar-group-radius, var(--xh-shape-pill));
+    background: var(--xh-avatar-group-overflow-bg, var(--xh-bg-muted));
+    color: var(--xh-avatar-group-overflow-fg, var(--xh-fg-muted));
+    font-size: var(--xh-_avatar-group-font-size);
+    font-weight: var(--xh-avatar-group-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+    user-select: none;
+  }
+
+  [data-scope='avatar-group'][data-part='overflow'][hidden] {
+    display: none;
+  }
+}

package/css/avatar.css

@@ -0,0 +1,55 @@
+@layer xihan.components {
+  [data-scope='avatar'][data-part='root'] {
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+    inline-size: var(--xh-avatar-size, var(--xh-control-h-md));
+    block-size: var(--xh-avatar-size, var(--xh-control-h-md));
+    border-radius: var(--xh-avatar-radius, var(--xh-shape-pill));
+    background: var(--xh-avatar-bg, var(--xh-bg-subtle));
+    color: var(--xh-avatar-fg, var(--xh-fg-muted));
+    font-size: var(--xh-avatar-font-size, var(--xh-font-size-sm));
+    font-weight: var(--xh-avatar-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+    user-select: none;
+  }
+
+  /* 三档尺寸对齐控件档位，缺省档写在上面的基础规则里；
+     字号跟着一起缩放，回退字才在小头像里放得下、在大头像里不显小 */
+  [data-scope='avatar'][data-part='root'][data-size='sm'] {
+    inline-size: var(--xh-control-h-sm);
+    block-size: var(--xh-control-h-sm);
+    font-size: var(--xh-font-size-xs);
+  }
+
+  [data-scope='avatar'][data-part='root'][data-size='lg'] {
+    inline-size: var(--xh-control-h-lg);
+    block-size: var(--xh-control-h-lg);
+    font-size: var(--xh-font-size-md);
+  }
+
+  /* 不声明 display，加载完成前的 hidden 直接交给浏览器的 [hidden] 规则收起 */
+  [data-scope='avatar'][data-part='image'] {
+    inline-size: 100%;
+    block-size: 100%;
+    border-radius: inherit;
+    object-fit: cover;
+  }
+
+  [data-scope='avatar'][data-part='fallback'] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 100%;
+    block-size: 100%;
+    text-transform: uppercase;
+  }
+
+  /* display 会盖掉 hidden 属性的 UA 规则，加载完成后显式让位给图片 */
+  [data-scope='avatar'][data-part='fallback'][hidden] {
+    display: none;
+  }
+}

package/css/back-top.css

@@ -0,0 +1,61 @@
+@layer xihan.components {
+  /* 定位壳：钉在视口的尾下角，用逻辑属性，RTL 下自动换到另一侧。
+     不声明 display —— 收起态由连接层写 hidden，UA 的 [hidden]{display:none} 得压得住 */
+  [data-scope='back-top'][data-part='root'] {
+    /* 尺寸档只换这一个私有槽，按钮从壳继承，换档不必给每个部件各写一条选择器 */
+    --xh-_back-top-size: var(--xh-control-h-md);
+
+    position: fixed;
+    inset-block-end: var(--xh-back-top-inset-block, var(--xh-space-8));
+    inset-inline-end: var(--xh-back-top-inset-inline, var(--xh-space-8));
+    z-index: var(--xh-back-top-layer, var(--xh-layer-sticky));
+  }
+
+  /* —— 尺寸 —— */
+  [data-scope='back-top'][data-part='root'][data-size='sm'] {
+    --xh-_back-top-size: var(--xh-control-h-sm);
+  }
+
+  [data-scope='back-top'][data-part='root'][data-size='lg'] {
+    --xh-_back-top-size: var(--xh-control-h-lg);
+  }
+
+  /* 圆形按钮：里面通常只放一个箭头图标，宽高同取一档尺寸 */
+  [data-scope='back-top'][data-part='trigger'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-back-top-trigger-size, var(--xh-_back-top-size));
+    block-size: var(--xh-back-top-trigger-size, var(--xh-_back-top-size));
+    padding: 0;
+    border: var(--xh-stroke-thin) solid var(--xh-back-top-border, var(--xh-border-default));
+    border-radius: var(--xh-back-top-radius, var(--xh-shape-pill));
+    /* 使用者令牌排在语气之前：写了覆盖钩子就以它为准，没写才退到语气，最后才是中性缺省 */
+    background: var(--xh-back-top-bg, var(--xh-bg-surface-raised));
+    color: var(--xh-back-top-fg, var(--xh-_tone-fg, var(--xh-fg-default)));
+    /* 浮在内容之上，靠投影与页面拉开层次 */
+    box-shadow: var(--xh-elevation-2);
+    cursor: pointer;
+    transition:
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 悬停只在能用指针的设备上生效，触摸端不留一个按不掉的悬停态 */
+  @media (hover: hover) {
+    [data-scope='back-top'][data-part='trigger']:hover {
+      border-color: var(--xh-back-top-border-hover, var(--xh-border-strong));
+      background: var(--xh-back-top-bg-hover, var(--xh-bg-subtle-hover));
+    }
+  }
+
+  [data-scope='back-top'][data-part='trigger']:active {
+    background: var(--xh-back-top-bg-active, var(--xh-bg-subtle-active));
+  }
+
+  /* 聚焦环恒是 --xh-ring-focus，不随语气走 */
+  [data-scope='back-top'][data-part='trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+}