@xihan-ui/styles 3.0.0 → 3.2.0

package/dist/css/avatar.css

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 avatar 样式。 */
+
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-avatar {
+    --xh-avatar-skin: 1;
+  }
+
+  .xh-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-circle));
+    /* 头像在头像组里层叠：底取淡底的不透明档，半透明会透出压在下面的那一枚 */
+    background: var(--xh-avatar-bg, var(--xh-bg-subtle-opaque));
+    color: var(--xh-avatar-fg, var(--xh-fg-muted));
+    font-size: var(--xh-avatar-font-size, var(--xh-text-secondary-size));
+    font-weight: var(--xh-avatar-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+    user-select: none;
+  }
+
+  /* 三档尺寸对齐控件档位，缺省档写在上面的基础规则里；
+     字号跟着一起缩放，回退字才在小头像里放得下、在大头像里不显小。
+     每一档都把 --xh-avatar-size / --xh-avatar-font-size 排在自己的档值前面：这两个槽是
+     外层统一整排头像的通道，档值直接写终值的话，写了 data-size 的那一枚就脱离外层控制 */
+  .xh-scope-avatar[data-part='root'][data-size='sm'] {
+    inline-size: var(--xh-avatar-size, var(--xh-control-h-sm));
+    block-size: var(--xh-avatar-size, var(--xh-control-h-sm));
+    font-size: var(--xh-avatar-font-size, var(--xh-control-caption-sm));
+  }
+
+  .xh-scope-avatar[data-part='root'][data-size='lg'] {
+    inline-size: var(--xh-avatar-size, var(--xh-control-h-lg));
+    block-size: var(--xh-avatar-size, var(--xh-control-h-lg));
+    font-size: var(--xh-avatar-font-size, var(--xh-control-caption-lg));
+  }
+
+  /* —— 语气 ——
+     头像只有「淡底 + 字/图」一种形态，所以语气只换淡底与字色这一档，不开形态轴。
+     两条声明都把 --xh-avatar-bg / --xh-avatar-fg 排在语气值前面：使用者槽仍是最外那一层，
+     写了 tone 的那一枚照样受外层统一控制。整块带 [data-tone] 限定，没写语气的头像逐值不变 */
+  .xh-scope-avatar[data-part='root'][data-tone] {
+    background: var(--xh-avatar-bg, var(--xh-_tone-subtle, var(--xh-bg-subtle-opaque)));
+    color: var(--xh-avatar-fg, var(--xh-_tone-fg, var(--xh-fg-muted)));
+  }
+
+  /* 不声明 display，加载完成前的 hidden 直接交给浏览器的 [hidden] 规则收起。
+     载完那一刻 hidden 撤掉、这个节点从不显示变为显示，淡入在那一刻起跑；
+     回退内容同一刻开始淡出（见下），两者交叉，中间不露一拍底色 */
+  .xh-scope-avatar[data-part='image'] {
+    inline-size: 100%;
+    block-size: 100%;
+    border-radius: inherit;
+    object-fit: cover;
+    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  .xh-scope-avatar[data-part='fallback'] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 100%;
+    block-size: 100%;
+    text-transform: uppercase;
+  }
+
+  /* 图片载好：回退内容浮到图片之上原地淡出，与图片的淡入交叉；播完连接层才写 hidden */
+  .xh-scope-avatar[data-part='fallback'][data-state='loaded'] {
+    position: absolute;
+    inset: 0;
+    animation: xh-fade-out var(--xh-motion-duration-enter) var(--xh-motion-ease-enter) forwards;
+  }
+
+  /* display 会盖掉 hidden 属性的 UA 规则：载入中等过 fallbackDelay 之前、以及淡出播完之后收起 */
+  .xh-scope-avatar[data-part='fallback'][hidden] {
+    display: none;
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  .xh-scope-avatar[data-part='root'][hidden] {
+    display: none;
+  }
+}

package/dist/css/back-top.css

@@ -0,0 +1,161 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 back top 样式。 */
+
+@import '../family/action-control.css';
+@import '../family/motion.css';
+@import '../family/material.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-back-top {
+    --xh-back-top-skin: 1;
+  }
+
+  /* 定位壳：钉在视口的尾下角，用逻辑属性，RTL 下自动换到另一侧。
+     不声明 display —— 收起态由连接层写 hidden，UA 的 [hidden]{display:none} 得压得住 */
+  .xh-scope-back-top[data-part='root'] {
+    position: fixed;
+    /* 贴边与安全区取大的一头：底部横条与圆角压住的那一段由系统给出，贴边比它窄时钮会被切掉一角。
+       桌面上 env() 恒为 0，取值与贴边槽完全一致。安全区只有物理方向的名字，
+       行内轴上两侧同取较宽的那一段，RTL 下不会翻错边。 */
+    inset-block-end: max(var(--xh-back-top-inset-block, var(--xh-space-8)), env(safe-area-inset-bottom));
+    inset-inline-end: max(
+      var(--xh-back-top-inset-inline, var(--xh-space-8)),
+      env(safe-area-inset-left),
+      env(safe-area-inset-right)
+    );
+    z-index: var(--xh-back-top-layer, var(--xh-layer-sticky));
+  }
+
+  /* —— 触发器 ——
+     浮在内容之上的单图标圆钮，接 Action Control floating 档：盒型（md = box-lg 48px，圆形）、
+     四态面、0.97 按压与 44px 命中区由家族配方按 data-xh-action-variant / -size 给出。
+     这里只把公开槽桥接到矩阵之前（使用者槽 → 形态矩阵 → 家族缺省）与几何槽映射。
+     整件只有这一颗按钮，槽名与其余一样不带部件段（照 float-button 的 --xh-float-button-size） */
+  .xh-scope-back-top[data-part='trigger'] {
+    --xh-action-bg-rest: var(--xh-back-top-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-back-top-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-back-top-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-bg-focus-visible: var(--xh-back-top-bg, var(--xh-_action-variant-bg-focus-visible));
+    --xh-action-bg-disabled: var(--xh-back-top-bg, var(--xh-_action-variant-bg-disabled));
+    --xh-action-fg-rest: var(--xh-back-top-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-back-top-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-back-top-fg, var(--xh-_action-variant-fg-pressed));
+    --xh-action-fg-focus-visible: var(--xh-back-top-fg, var(--xh-_action-variant-fg-focus-visible));
+    --xh-action-border-rest: var(--xh-back-top-border, var(--xh-_action-variant-border-rest));
+    --xh-action-border-hover: var(--xh-back-top-border-hover, var(--xh-_action-variant-border-hover));
+    --xh-action-border-pressed: var(--xh-back-top-border-hover, var(--xh-_action-variant-border-pressed));
+    --xh-action-border-focus-visible: var(--xh-back-top-border, var(--xh-_action-variant-border-focus-visible));
+    --xh-action-border-disabled: var(--xh-back-top-border, var(--xh-_action-variant-border-disabled));
+    /* 矩阵各态无影（淡底与阴影互斥）；outline 那一档的磨砂投影在下面另桥接 */
+    --xh-action-shadow-rest: var(--xh-back-top-shadow, none);
+    --xh-action-shadow-hover: var(--xh-back-top-shadow, none);
+    --xh-action-shadow-pressed: var(--xh-back-top-shadow, none);
+    --xh-action-shadow-focus-visible: var(--xh-back-top-shadow, none);
+    --xh-action-shadow-disabled: var(--xh-back-top-shadow, none);
+    --xh-action-radius: var(--xh-back-top-radius, var(--xh-_action-profile-radius));
+    --xh-action-visual-size: var(--xh-back-top-size, var(--xh-_action-profile-visual-size));
+    /* 作者塞进来的图标跟着 floating 档走（md 24px），与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-back-top-icon-size, var(--xh-_action-profile-glyph-size));
+  }
+
+  /* 缺省 outline 是 frosted 材质面：连接层只在这一档投影 data-xh-material，面由材质家族配方给——
+     底、描边、投影、1px 顶光与背景滤镜一份取值，高对比、减少透明度、打印和强制色沿同一令牌通道降级。
+     悬停 / 按下换不透明的淡底一档、二档，边缘与投影不动；键盘聚焦时铺实体 focus surface——透明面上的
+     内收环不能依赖页面底色；置灰只换字色，面仍留着 */
+  .xh-scope-back-top[data-part='root'][data-variant='outline']
+    .xh-scope-back-top[data-part='trigger'] {
+    /* 面走材质家族配方（family/material.css）：frosted 档的底、交互阶梯、描边、投影、1px 顶光与背景滤镜，
+       liquid 档由配方换成液态面；这里把使用者槽接到 Action Control 的桥接槽 */
+    --xh-action-bg-rest: var(--xh-back-top-bg, var(--xh-_material-bg));
+    --xh-action-bg-hover: var(--xh-back-top-bg-hover, var(--xh-_material-bg-hover));
+    --xh-action-bg-pressed: var(--xh-back-top-bg-active, var(--xh-_material-bg-pressed));
+    --xh-action-bg-focus-visible: var(--xh-back-top-bg, var(--xh-_material-bg-focus));
+    --xh-action-bg-disabled: var(--xh-back-top-bg, var(--xh-_material-bg));
+    --xh-action-fg-rest: var(--xh-back-top-fg, var(--xh-_material-fg));
+    --xh-action-fg-hover: var(--xh-back-top-fg, var(--xh-_material-fg));
+    --xh-action-fg-pressed: var(--xh-back-top-fg, var(--xh-_material-fg));
+    --xh-action-fg-focus-visible: var(--xh-back-top-fg, var(--xh-_material-fg));
+    --xh-action-border-rest: var(--xh-back-top-border, var(--xh-_material-border));
+    --xh-action-border-hover: var(--xh-back-top-border-hover, var(--xh-_material-border));
+    --xh-action-border-pressed: var(--xh-back-top-border-hover, var(--xh-_material-border));
+    --xh-action-border-focus-visible: var(--xh-back-top-border, var(--xh-_material-border));
+    --xh-action-border-disabled: var(--xh-back-top-border, var(--xh-_material-border));
+    --xh-action-shadow-rest: var(--xh-back-top-shadow, var(--xh-_material-shadow));
+    --xh-action-shadow-hover: var(--xh-back-top-shadow, var(--xh-_material-shadow));
+    --xh-action-shadow-pressed: var(--xh-back-top-shadow, var(--xh-_material-shadow));
+    --xh-action-shadow-focus-visible: var(--xh-back-top-shadow, var(--xh-_material-shadow));
+    --xh-action-shadow-disabled: var(--xh-back-top-shadow, var(--xh-_material-shadow));
+    --xh-action-highlight-rest: var(--xh-_material-highlight);
+    --xh-action-highlight-hover: var(--xh-_material-highlight);
+    --xh-action-highlight-pressed: var(--xh-_material-highlight);
+    --xh-action-highlight-focus-visible: var(--xh-_material-highlight);
+    --xh-action-highlight-disabled: var(--xh-_material-highlight);
+    /* M2 顶光走配方的高光通道：实心、淡色与透空形态各有自身表面，不能把磨砂高光误铺上去 */
+  }
+
+  /* 面是实心的，环色与面同族，画在面里就看不出来；环改取面自己的前景色——
+     那一族色本来就要在这块面上把字读清楚，与面的对比是按可读性定的 */
+  .xh-scope-back-top[data-part='trigger'][data-xh-action-variant='solid']:focus-visible {
+    --xh-action-ring-color-focus-visible: currentColor;
+  }
+
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中。
+     粗指针的 44px 命中区由配方的 ::after 给，字形占的是 ::before */
+  .xh-scope-back-top[data-part='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;
+  }
+
+  /* 过线露面时弹出；退回线内时先播完退场、连接层才给根写 hidden 收起。退场途中不再接指针 */
+  .xh-scope-back-top[data-part='trigger'][data-state='visible'] {
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+  }
+
+  .xh-scope-back-top[data-part='trigger'][data-state='hidden'] {
+    pointer-events: none;
+    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
+  /* 配方声明过 display，会盖掉 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  .xh-scope-back-top[data-part='trigger'][hidden] {
+    display: none;
+  }
+
+  @media print {
+    /* 打印：回到顶部这颗钮只有在能滚的地方才成立，落到纸上是一颗按不动的按钮。 */
+    .xh-scope-back-top[data-part='root'] {
+      display: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    /* 兜底字形是 mask 挖出来的一块底色，这一档里底色被系统换成 Canvas，字形跟着消失。
+       字形退出强制换色、直接写系统色（不能取 currentColor：退出强制换色的伪元素读到的是被系统换掉之前的作者色）：
+       按钮面上取 ButtonText，悬停与按下时家族把按钮涂成 Highlight、字形换 HighlightText；
+       禁用取 GrayText */
+    .xh-scope-back-top[data-part='trigger']:empty::before {
+      forced-color-adjust: none;
+      background-color: ButtonText;
+    }
+
+    .xh-scope-back-top[data-part='trigger']:not([data-disabled]):not([data-loading]):is(:hover, :active, [data-pressed]):empty::before {
+      background-color: HighlightText;
+    }
+
+    .xh-scope-back-top[data-part='trigger'][data-disabled]:empty::before {
+      background-color: GrayText;
+    }
+  }
+}

package/dist/css/badge.css

@@ -0,0 +1,205 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 badge 样式。 */
+
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-badge {
+    --xh-badge-skin: 1;
+  }
+
+  /* 锚点：被标记的那个东西（按钮、头像、标签页）放进它里面。
+     角标绝对定位在它的角上，所以这一层必须建定位上下文，且不能自己撑出尺寸 */
+  .xh-scope-badge[data-part='root'] {
+    position: relative;
+    display: inline-flex;
+    /* 角标探出宿主边界是常态，不能被裁掉 */
+    overflow: visible;
+    vertical-align: middle;
+  }
+
+  /* 锚点也可能被作者整块收起 */
+  .xh-scope-badge[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 角标本身。档位换的是圆点直径、两位数时的最小宽度与字号——
+     不是药丸那套内衬与行高：那是 tag 的活 */
+  .xh-scope-badge[data-part='indicator'] {
+    /* 每一档的盒都要大于字号：两位数在等高的盒里会被撑破。
+       字号刻度最小就是 12px，所以往上抬盒子而不是往下压字。
+       盒只比字高一档：20px 扣掉两道 1px 描边还剩 18px 内高，13px 的两位数与「99+」立得住，
+       角标又不会大过它贴着的宿主文字 */
+    --xh-_badge-dot: var(--xh-space-2);
+    --xh-_badge-min: var(--xh-space-5);
+    --xh-_badge-px: var(--xh-space-1);
+    --xh-_badge-font: var(--xh-text-secondary-size);
+
+    /* 不设 z-index：角标在 DOM 序里排在宿主之后，本来就压在上面 */
+    position: absolute;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    min-inline-size: var(--xh-badge-min-size, var(--xh-_badge-min));
+    block-size: var(--xh-badge-min-size, var(--xh-_badge-min));
+    padding-inline: var(--xh-badge-px, var(--xh-_badge-px));
+    border: var(--xh-stroke-thin) solid var(--xh-badge-ring, var(--xh-bg-surface));
+    border-radius: var(--xh-badge-radius, var(--xh-shape-pill));
+    /* 角标默认就是实心的：贴在别的东西上，淡底与描边都看不清 */
+    background: var(--xh-badge-bg, var(--xh-_tone));
+    color: var(--xh-badge-fg, var(--xh-_tone-on));
+    font-size: var(--xh-badge-font-size, var(--xh-_badge-font));
+    font-weight: var(--xh-badge-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+    /* 出的是计数，数字必须等宽：不然 9 跳到 10 时角标的宽度会抖一下 */
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+    pointer-events: none;
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     计数为 0 且没开 showZero 时连接层会发 hidden */
+  .xh-scope-badge[data-part='indicator'][hidden] {
+    display: none;
+  }
+
+  /* 圆点形态：只表示「有」，不表示「有几个」——收掉内边距与文字盒。
+     宽高同槽的正方盒按身份取 circle，不沿用计数档的胶囊冒充圆：
+     胶囊那 9999px 在正方盒上虽也画成圆，形状身份却写错了档，作者按圆点覆盖圆角时无处落手。
+     圆点直径只有六到十像素，一像素的内高光会占去顶上一大截、读成缺了一圈的描边，这里收掉 */
+  .xh-scope-badge[data-part='indicator'][data-dot] {
+    min-inline-size: var(--xh-badge-dot-size, var(--xh-_badge-dot));
+    inline-size: var(--xh-badge-dot-size, var(--xh-_badge-dot));
+    block-size: var(--xh-badge-dot-size, var(--xh-_badge-dot));
+    border-radius: var(--xh-badge-dot-radius, var(--xh-shape-circle));
+    padding: 0;
+    box-shadow: none;
+    font-size: 0;
+  }
+
+  /* 呼吸：圆点表达正在进行、给不出进度的状态（直播、录制、通话中）。
+     明暗与缩放的起伏持续到状态结束；外扩光环画在 ::after 上，同周期播 3 轮后停在不可见。
+     数字角标不呼吸：连接层只在圆点档投影 data-pulse，明暗起伏会压低数字的对比度 */
+  .xh-scope-badge[data-part='indicator'][data-pulse] {
+    animation: xh-breathe var(--xh-motion-loop-breathe) var(--xh-motion-ease-breathe) infinite;
+  }
+
+  .xh-scope-badge[data-part='indicator'][data-pulse]::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    background: inherit;
+    opacity: 0;
+    pointer-events: none;
+    animation: xh-breathe-halo var(--xh-motion-loop-breathe) var(--xh-motion-ease-breathe) 3;
+  }
+
+  /* 减弱动效：两者都停，圆点停在满不透明度，光环不出现；状态仍由圆点本身与宿主的文字表达 */
+  @media (prefers-reduced-motion: reduce) {
+    .xh-scope-badge[data-part='indicator'][data-pulse],
+    .xh-scope-badge[data-part='indicator'][data-pulse]::after {
+      animation: none;
+    }
+  }
+
+  :where([data-motion='reduce']) .xh-scope-badge[data-part='indicator'][data-pulse],
+  :where([data-motion='reduce']) .xh-scope-badge[data-part='indicator'][data-pulse]::after {
+    animation: none;
+  }
+
+  /* 出现与消失：计数从无到有时原地弹出；清零时缩小淡出，播完连接层才写 hidden，退场那几帧照清零前的数字写。
+     首帧就在的角标直接呈现（data-instant）；呼吸的圆点不叠进场，两段明暗会打架。
+     写在呼吸之后：退场压过呼吸。减弱动效下缩放归一、只剩淡变 */
+  .xh-scope-badge[data-part='indicator'][data-state='visible']:not([data-instant], [data-pulse]) {
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+  }
+
+  .xh-scope-badge[data-part='indicator'][data-state='hidden'] {
+    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
+  /* —— 落点 —— */
+  /* 用 inset 的逻辑属性写，rtl 下 end 自动落到左边；translate 让角标压住宿主的角。
+     两个偏移槽微调角标离角多远：正值朝行内末端、块末端挪（rtl 下行内末端在左），
+     宿主是圆形头像、角上留白多时往里收一点。四个角各按贴哪条边换正负号，同一个值在哪个角都朝同一个方向挪 */
+  .xh-scope-badge[data-part='indicator'][data-placement='top-end'] {
+    inset-block-start: var(--xh-badge-offset-block, var(--xh-space-0));
+    inset-inline-end: calc(-1 * var(--xh-badge-offset-inline, var(--xh-space-0)));
+    translate: 25% -25%;
+  }
+
+  .xh-scope-badge[data-part='indicator'][data-placement='top-start'] {
+    inset-block-start: var(--xh-badge-offset-block, var(--xh-space-0));
+    inset-inline-start: var(--xh-badge-offset-inline, var(--xh-space-0));
+    translate: -25% -25%;
+  }
+
+  .xh-scope-badge[data-part='indicator'][data-placement='bottom-end'] {
+    inset-block-end: calc(-1 * var(--xh-badge-offset-block, var(--xh-space-0)));
+    inset-inline-end: calc(-1 * var(--xh-badge-offset-inline, var(--xh-space-0)));
+    translate: 25% 25%;
+  }
+
+  .xh-scope-badge[data-part='indicator'][data-placement='bottom-start'] {
+    inset-block-end: calc(-1 * var(--xh-badge-offset-block, var(--xh-space-0)));
+    inset-inline-start: var(--xh-badge-offset-inline, var(--xh-space-0));
+    translate: -25% 25%;
+  }
+
+  /* rtl 下 translate 的行内轴要跟着翻，否则角标会往宿主外面跑 */
+  [dir='rtl'] .xh-scope-badge[data-part='indicator'][data-placement='top-end'] {
+    translate: -25% -25%;
+  }
+
+  [dir='rtl'] .xh-scope-badge[data-part='indicator'][data-placement='top-start'] {
+    translate: 25% -25%;
+  }
+
+  [dir='rtl'] .xh-scope-badge[data-part='indicator'][data-placement='bottom-end'] {
+    translate: -25% 25%;
+  }
+
+  [dir='rtl'] .xh-scope-badge[data-part='indicator'][data-placement='bottom-start'] {
+    translate: 25% 25%;
+  }
+
+  /* —— 尺寸 —— */
+  /* 小号是贴在 16px 图标角上的角标：盒取 12 + 2 的半阶补偿 = 14px，字仍是刻度最小的 12px——
+     数字的字面只占字号的六成，扣掉两道 1px 描边后的 12px 内高装得下两位数，再小就得压字 */
+  .xh-scope-badge[data-part='indicator'][data-size='sm'] {
+    --xh-_badge-dot: var(--xh-space-1_5);
+    --xh-_badge-min: calc(var(--xh-space-3) + var(--xh-space-0_5));
+    --xh-_badge-px: var(--xh-space-0_5);
+    --xh-_badge-font: var(--xh-text-caption-size);
+  }
+
+  /* 大号只往上抬一级：盒 24px、字 14px，仍是角标，不长成与宿主同级的一枚按钮 */
+  .xh-scope-badge[data-part='indicator'][data-size='lg'] {
+    --xh-_badge-dot: var(--xh-space-2_5);
+    --xh-_badge-min: var(--xh-space-6);
+    --xh-_badge-px: var(--xh-space-1_5);
+    --xh-_badge-font: var(--xh-text-body-size);
+  }
+
+  /*
+   * 打印：底色被丢掉。计数档配的是实心底上的前景色，底一没那串数字就印不出来；
+   * 圆点档整个由底色画成，底一没连位置都看不见。
+   * 两档都改由描边承载：常态那圈边是衬在宿主上的隔离环，取的是面色，纸上同样是白的，
+   * 这里换成正文色——计数成了一枚描边药丸，圆点成了一个小圈。
+   */
+  @media print {
+    .xh-scope-badge[data-part='indicator'] {
+      border-color: currentColor;
+      color: var(--xh-fg-default);
+      box-shadow: none;
+    }
+  }
+}

package/dist/css/bar-code.css

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 bar code 样式。 */
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-bar-code {
+    --xh-bar-code-skin: 1;
+  }
+
+  /*
+   * 根 <svg>。深浅两色取固定档而不是语义前景/背景：语义色跟着主题走，深色主题下整张码
+   * 会翻成浅底深条的反相图，读码器按"深条浅底"取样，反相码扫不出来。要换配色改下面这两个覆盖槽。
+   *
+   * 换色只有一条硬约束：条必须比底色深，且两者对比要足。反相与深浅相近都会让读码器扫不出来，
+   * 而这件事肉眼看不出来。
+   *
+   *   --xh-bar-code-fg  条色，同时经 currentColor 传给人读文字
+   *   --xh-bar-code-bg  底色
+   */
+  .xh-scope-bar-code[data-part='root'] {
+    display: block;
+    border-radius: var(--xh-bar-code-radius, var(--xh-shape-control));
+    background: var(--xh-bar-code-bg, var(--xh-color-neutral-0));
+
+    /* 条那条 path 不带自己的填充色，从这里继承下去 */
+    color: var(--xh-bar-code-fg, var(--xh-color-neutral-950));
+    fill: currentColor;
+
+    /* 占位与码面之间来回时，底色与那圈描边淡变 */
+    transition:
+      background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      box-shadow var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  .xh-scope-bar-code[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /*
+   * 人读文字：字号由 connect 按 X 尺寸写在节点上（规范里数字高约 8X），这里只定字体。
+   * 等宽字体让每位数字一样宽，EAN 逐位居中落格才整齐；规范要的 OCR-B 一般机器上没有，退到系统等宽。
+   */
+  .xh-scope-bar-code[data-part='root'] > [data-xh-geom='text'] {
+    font-family: var(--xh-bar-code-font-family, var(--xh-font-family-mono));
+    fill: var(--xh-bar-code-text-fg, currentColor);
+  }
+
+  /*
+   * 没有可编码的内容、以及内容不合规则：两种情形都一根条不铺，留一块带描边的占位。
+   * 占位用的是语义色——它是界面元素不是码面，跟着主题走才对。
+   */
+  .xh-scope-bar-code[data-part='root'][data-state='empty'],
+  .xh-scope-bar-code[data-part='root'][data-state='error'] {
+    background: var(--xh-bar-code-placeholder-bg, var(--xh-bg-subtle));
+    box-shadow: inset 0 0 0 var(--xh-stroke-thin) var(--xh-bar-code-placeholder-border, var(--xh-border-default));
+  }
+}