@xihan-ui/styles 1.0.0-alpha.0

package/css/cascader.css

@@ -0,0 +1,397 @@
+@layer xihan.components {
+  /* 解剖里没有把「触发器 + 清空按钮」裹在一起的 control 部件，一行是靠 flex-wrap 分出来的：
+     标签占满整行把后面的挤到下一行，触发器与清空按钮就并排落在同一行上。
+     这样作者少写标签、少写清空按钮，剩下的部件也不会塌 */
+  [data-scope='cascader'][data-part='root'] {
+    /* 尺寸档只换这几个私有槽，触发框与列里的条目都从 root 继承它们，换档不必给每个部件各写一条选择器 */
+    --xh-_cascader-h: var(--xh-control-h-md);
+    --xh-_cascader-px: var(--xh-control-px-md);
+    --xh-_cascader-gap: var(--xh-control-gap-md);
+    --xh-_cascader-font-size: var(--xh-text-body-size);
+    --xh-_cascader-label-font-size: var(--xh-text-label-size);
+
+    /* 形态档只换触发框的描边与底色这三个槽，浮层与列不跟着变：
+       变的是「这是个输入位」的表达方式，不是弹出内容的表达方式 */
+    --xh-_cascader-border: var(--xh-border-default);
+    --xh-_cascader-border-hover: var(--xh-border-strong);
+    --xh-_cascader-bg: var(--xh-bg-canvas);
+
+    /* 选中条目的文字色随语气走，没写 data-tone 时退回品牌强调色 */
+    --xh-_cascader-selected-fg: var(--xh-_tone-fg, var(--xh-fg-brand-strong));
+
+    display: inline-flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--xh-cascader-gap, var(--xh-space-1));
+  }
+
+  /* 只要声明了 display 就盖掉了 UA 的 [hidden]{display:none}，作者手动收起时要自己还回去 */
+  [data-scope='cascader'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 形态 —— */
+  /* 形态只决定描边与底色怎么用；用哪族颜色由 data-tone 决定，没写 tone 就沿用原来的中性配色 */
+  /* outline 就是缺省那一身：描边加画布底，写出来只为让三档并列可读 */
+  [data-scope='cascader'][data-part='root'][data-variant='outline'] {
+    --xh-_cascader-border: var(--xh-border-default);
+    --xh-_cascader-border-hover: var(--xh-border-strong);
+    --xh-_cascader-bg: var(--xh-bg-canvas);
+  }
+
+  /* subtle 是填充式：底色接过「这里能点」的表达，描边随之让位 */
+  [data-scope='cascader'][data-part='root'][data-variant='subtle'] {
+    --xh-_cascader-border: transparent;
+    --xh-_cascader-border-hover: var(--xh-_tone-border, var(--xh-border-default));
+    --xh-_cascader-bg: var(--xh-_tone-subtle, var(--xh-bg-subtle));
+  }
+
+  /* ghost 无框无底，可见反馈只在聚焦时给；边框宽度仍占位，切换形态不引起布局抖动 */
+  [data-scope='cascader'][data-part='root'][data-variant='ghost'] {
+    --xh-_cascader-border: transparent;
+    --xh-_cascader-border-hover: transparent;
+    --xh-_cascader-bg: transparent;
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  [data-scope='cascader'][data-part='root'][data-size='sm'] {
+    --xh-_cascader-h: var(--xh-control-h-sm);
+    --xh-_cascader-px: var(--xh-control-px-sm);
+    --xh-_cascader-gap: var(--xh-control-gap-sm);
+    --xh-_cascader-font-size: var(--xh-font-size-sm);
+    --xh-_cascader-label-font-size: var(--xh-font-size-sm);
+  }
+
+  [data-scope='cascader'][data-part='root'][data-size='lg'] {
+    --xh-_cascader-h: var(--xh-control-h-lg);
+    --xh-_cascader-px: var(--xh-control-px-lg);
+    --xh-_cascader-gap: var(--xh-control-gap-lg);
+    --xh-_cascader-font-size: var(--xh-font-size-lg);
+    --xh-_cascader-label-font-size: var(--xh-font-size-lg);
+  }
+
+  [data-scope='cascader'][data-part='label'] {
+    /* 占满整行，把触发器那一行挤下去 */
+    flex-basis: 100%;
+    color: var(--xh-cascader-label-fg, var(--xh-fg-muted));
+    font-size: var(--xh-cascader-label-font-size, var(--xh-_cascader-label-font-size));
+    font-weight: var(--xh-cascader-label-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-none);
+  }
+
+  /* 整个控件禁用会把 data-disabled 一路打到 label / value-text / indicator 上，各处观感保持一致 */
+  [data-scope='cascader'][data-part='label'][data-disabled] {
+    color: var(--xh-fg-subtle);
+  }
+
+  /* 画成一个框的就是 trigger 自己：整条路径的回显与展开箭头都长在它里面，
+     清空按钮贴在框外与它并排 */
+  [data-scope='cascader'][data-part='trigger'] {
+    display: inline-flex;
+    flex: 1;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--xh-cascader-trigger-gap, var(--xh-_cascader-gap));
+    min-inline-size: var(--xh-cascader-trigger-min-w, 14rem);
+    block-size: var(--xh-cascader-trigger-h, var(--xh-_cascader-h));
+    padding-inline: var(--xh-cascader-trigger-px, var(--xh-_cascader-px));
+    border: var(--xh-stroke-thin) solid var(--xh-cascader-trigger-border, var(--xh-_cascader-border));
+    border-radius: var(--xh-cascader-trigger-radius, var(--xh-shape-control));
+    background: var(--xh-cascader-trigger-bg, var(--xh-_cascader-bg));
+    color: var(--xh-cascader-trigger-fg, var(--xh-fg-default));
+    font-family: inherit;
+    font-size: var(--xh-cascader-trigger-font-size, var(--xh-_cascader-font-size));
+    line-height: var(--xh-leading-none);
+    text-align: start;
+    cursor: pointer;
+    transition: border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='cascader'][data-part='trigger'][hidden] {
+    display: none;
+  }
+
+  /* hover 只在中性态换描边：invalid 正拿边框颜色说事，被 hover 盖掉那条信息就没了 */
+  [data-scope='cascader'][data-part='trigger']:hover:not(:disabled, [data-invalid]) {
+    border-color: var(--xh-cascader-trigger-border-hover, var(--xh-_cascader-border-hover));
+  }
+
+  /* trigger 是整个控件唯一的 Tab 停靠点（展开后停靠点才移进列里），落焦必须看得见。
+     语气落在环上：没写 data-tone 时 --xh-_tone 没被声明，退回原来的聚焦环色 */
+  [data-scope='cascader'][data-part='trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-_tone, var(--xh-ring-focus));
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  [data-scope='cascader'][data-part='trigger'][data-invalid] {
+    border-color: var(--xh-cascader-trigger-border-invalid, var(--xh-color-danger-500));
+  }
+
+  /* 只读仍可聚焦、浮层仍展得开、列仍能浏览，所以不置灰，只把底色压下去表示「改不动」 */
+  [data-scope='cascader'][data-part='trigger'][data-readonly] {
+    background: var(--xh-cascader-trigger-bg-readonly, var(--xh-bg-subtle));
+  }
+
+  /* trigger 是单体控件，用原生 disabled（列里的集合条目一律 aria-disabled，写 :disabled 永不命中） */
+  [data-scope='cascader'][data-part='trigger']:disabled {
+    background: var(--xh-cascader-trigger-bg-disabled, var(--xh-bg-subtle));
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  /* 路径连起来会很长，必须能截断；框宽由 trigger 定，这里得允许自己被压缩 */
+  [data-scope='cascader'][data-part='value-text'] {
+    flex: 1;
+    min-inline-size: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  /* 无选中：显示的是 placeholder，画淡一档 */
+  [data-scope='cascader'][data-part='value-text'][data-placeholder] {
+    color: var(--xh-cascader-placeholder-fg, var(--xh-fg-subtle));
+  }
+
+  [data-scope='cascader'][data-part='value-text'][data-disabled] {
+    color: var(--xh-fg-disabled);
+  }
+
+  [data-scope='cascader'][data-part='indicator'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    color: var(--xh-cascader-indicator-fg, var(--xh-fg-muted));
+    transition: rotate var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='cascader'][data-part='indicator'][hidden] {
+    display: none;
+  }
+
+  [data-scope='cascader'][data-part='indicator'][data-state='open'] {
+    rotate: 180deg;
+  }
+
+  [data-scope='cascader'][data-part='indicator'][data-disabled] {
+    color: var(--xh-fg-disabled);
+  }
+
+  /* 贴在触发框旁边的小方钮，不撑高那一行 */
+  [data-scope='cascader'][data-part='clear-trigger'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-cascader-action-size, var(--xh-control-action-size));
+    block-size: var(--xh-cascader-action-size, var(--xh-control-action-size));
+    padding: 0;
+    border: 0;
+    border-radius: var(--xh-cascader-action-radius, var(--xh-shape-control));
+    background: var(--xh-cascader-action-bg, transparent);
+    color: var(--xh-cascader-action-fg, var(--xh-fg-muted));
+    font-family: inherit;
+    font-size: var(--xh-cascader-action-font-size, var(--xh-font-size-sm));
+    line-height: var(--xh-leading-none);
+    cursor: pointer;
+    user-select: none;
+    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='cascader'][data-part='clear-trigger'][hidden] {
+    display: none;
+  }
+
+  [data-scope='cascader'][data-part='clear-trigger']:hover:not(:disabled) {
+    background: var(--xh-cascader-action-bg-hover, var(--xh-bg-subtle-hover));
+    color: var(--xh-cascader-action-fg-hover, var(--xh-fg-default));
+  }
+
+  [data-scope='cascader'][data-part='clear-trigger']:active:not(:disabled) {
+    background: var(--xh-cascader-action-bg-active, var(--xh-bg-subtle-active));
+  }
+
+  /* 清空按钮退出了 Tab 序列（tabindex=-1），正常操作走不到这里；
+     留着是给程序化聚焦兜底，落焦时得看得见 */
+  [data-scope='cascader'][data-part='clear-trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-_tone, var(--xh-ring-focus));
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* 无选中、只读、整控件禁用三种情况下都按不动，用的是原生 disabled */
+  [data-scope='cascader'][data-part='clear-trigger']:disabled {
+    background: var(--xh-cascader-action-bg, transparent);
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
+  [data-scope='cascader'][data-part='positioner'] {
+    position: fixed;
+    z-index: var(--xh-layer-popover);
+    /* 空壳不吃指针，交互只发生在 content 里 */
+    pointer-events: none;
+  }
+
+  /* 锚点被滚出可视区：整个浮层随之收起 */
+  [data-scope='cascader'][data-part='positioner'][data-hidden] {
+    visibility: hidden;
+  }
+
+  /* 级联的骨架就在这一条上：列沿书写方向并排，一层一列。
+     横向随列数增减，因此不设固定宽度，只给每列自己的宽度 */
+  [data-scope='cascader'][data-part='content'] {
+    display: flex;
+    flex-direction: row;
+    align-items: stretch;
+    max-inline-size: var(--xh-cascader-content-max-w, 48rem);
+    border: var(--xh-stroke-thin) solid var(--xh-cascader-content-border, var(--xh-border-default));
+    border-radius: var(--xh-cascader-content-radius, var(--xh-shape-surface));
+    background: var(--xh-cascader-content-bg, var(--xh-bg-surface));
+    color: var(--xh-cascader-content-fg, var(--xh-fg-default));
+    box-shadow: var(--xh-cascader-content-shadow, var(--xh-elevation-2));
+    /* 列多到放不下时整体横向滚动；纵向溢出归每一列自己 */
+    overflow-x: auto;
+    pointer-events: auto;
+  }
+
+  /* 收起态的唯一开关：display 盖掉了 UA 的 [hidden]{display:none}，漏了这条浮层就收不起来 */
+  [data-scope='cascader'][data-part='content'][hidden] {
+    display: none;
+  }
+
+  /* 容器只是焦点域的兜底落点，落焦不画环：高亮永远长在条目上 */
+  [data-scope='cascader'][data-part='content']:focus-visible {
+    outline: none;
+  }
+
+  [data-scope='cascader'][data-part='content'][data-state='open'] {
+    animation: xh-cascader-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 一列：自己定宽、自己滚。列与列之间用一条分隔线，比留白更能说明「这是下一级」 */
+  [data-scope='cascader'][data-part='column'] {
+    display: flex;
+    flex: none;
+    flex-direction: column;
+    inline-size: var(--xh-cascader-column-w, 11rem);
+    max-block-size: var(--xh-cascader-column-max-h, 16rem);
+    padding-block: var(--xh-cascader-column-py, var(--xh-space-1));
+    padding-inline: var(--xh-cascader-column-px, var(--xh-space-1));
+    overflow-y: auto;
+  }
+
+  /* 展开路径砍短了这一列就收起来。display 盖掉了 UA 的 [hidden]{display:none}，
+     漏了这条「选了靠左的一列就把右边的列砍掉」在视觉上根本不会发生 */
+  [data-scope='cascader'][data-part='column'][hidden] {
+    display: none;
+  }
+
+  /* 分隔线画在列的起始缘，且第一列不画：这样列数增减时线永远只出现在列与列之间。
+     用逻辑属性，rtl 下自动跑到另一侧 */
+  [data-scope='cascader'][data-part='column'] + [data-scope='cascader'][data-part='column'] {
+    border-inline-start: var(--xh-stroke-thin) solid var(--xh-cascader-column-divider, var(--xh-border-subtle));
+  }
+
+  /* 列不进 Tab 序列也不承载焦点，落焦不画环：高亮永远长在条目上 */
+  [data-scope='cascader'][data-part='column']:focus-visible {
+    outline: none;
+  }
+
+  [data-scope='cascader'][data-part='item'] {
+    display: flex;
+    align-items: center;
+    gap: var(--xh-cascader-row-gap, var(--xh-_cascader-gap));
+    padding-block: var(--xh-cascader-row-py, var(--xh-space-1));
+    padding-inline: var(--xh-cascader-row-px, var(--xh-control-px-sm));
+    border-radius: var(--xh-cascader-row-radius, var(--xh-shape-control));
+    color: var(--xh-cascader-row-fg, var(--xh-fg-default));
+    font-size: var(--xh-cascader-row-font-size, var(--xh-_cascader-font-size));
+    /* 行高留出文字的上下伸展空间，行内那层 overflow:hidden 才不会把字削掉 */
+    line-height: var(--xh-cascader-row-leading, var(--xh-leading-normal));
+    white-space: nowrap;
+    cursor: pointer;
+    user-select: none;
+  }
+
+  /* 条目常挂不卸载：不属于当前这一列的那些靠 hidden 收起。
+     display 盖掉了 UA 的 [hidden]{display:none}，漏了这条列换了内容旧条目还留在那儿 */
+  [data-scope='cascader'][data-part='item'][hidden] {
+    display: none;
+  }
+
+  /* 指针悬停、键盘高亮与展开路径共用同一张底：三者都是「此刻停在这儿」，
+     data-highlighted 跟的是连接层记的焦点条目 */
+  [data-scope='cascader'][data-part='item']:not([data-disabled]):is(:hover, [data-highlighted], [data-active]) {
+    background: var(--xh-cascader-row-bg-highlight, var(--xh-bg-subtle-hover));
+  }
+
+  /* 选中只换文字色与字重，配合行尾的 ✓ 标记；底色整条通道留给悬停，
+     两者因此能同时看见 */
+  [data-scope='cascader'][data-part='item'][data-selected] {
+    color: var(--xh-cascader-row-fg-selected, var(--xh-_cascader-selected-fg));
+    font-weight: var(--xh-cascader-row-selected-font-weight, var(--xh-font-weight-medium));
+  }
+
+  /* 条目自己就是 option，环直接画在它身上；往内收，行是撑满列宽的，环画在外沿会被裁掉 */
+  [data-scope='cascader'][data-part='item']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-_tone, var(--xh-ring-focus));
+    outline-offset: calc(-1 * var(--xh-ring-width));
+  }
+
+  /* 禁用走 aria-disabled 而非原生 disabled：条目仍要可聚焦（它还得当方向键的起点），
+     所以只能靠 data-disabled 表达，写 :disabled 永远不命中 */
+  [data-scope='cascader'][data-part='item'][data-disabled] {
+    color: var(--xh-fg-disabled);
+    cursor: not-allowed;
+  }
+
+  [data-scope='cascader'][data-part='item-text'] {
+    flex: 1;
+    min-inline-size: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  /* 勾选标记只在选中项上出现；未选中时占位不塌，切换选中不引起行宽抖动 */
+  [data-scope='cascader'][data-part='item-indicator'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-cascader-indicator-size, var(--xh-control-indicator-size));
+    color: var(--xh-cascader-item-indicator-fg, var(--xh-_tone, var(--xh-bg-brand)));
+    visibility: hidden;
+  }
+
+  [data-scope='cascader'][data-part='item-indicator'][hidden] {
+    display: none;
+  }
+
+  [data-scope='cascader'][data-part='item-indicator'][data-selected] {
+    visibility: visible;
+  }
+
+  [data-scope='cascader'][data-part='item-indicator'][data-disabled] {
+    color: var(--xh-fg-disabled);
+  }
+}
+
+@layer xihan.motion {
+  /* 浮层是横向长出来的：淡入之外再沿书写方向起始缘推一小段，观感上像列被「拉开」。
+     关键帧写在本文件里、名字带组件前缀，不动公共的那一份 */
+  @keyframes xh-cascader-in {
+    from {
+      opacity: 0;
+      translate: -0.25rem 0;
+    }
+
+    to {
+      opacity: 1;
+      translate: 0 0;
+    }
+  }
+}

package/css/checkbox-group.css

@@ -0,0 +1,185 @@
+@layer xihan.components {
+  /* 组容器：label、trigger、条目都是它的直接子节点，排布方式只能读 data-orientation——
+     连接层明说了 role=group 不接受 aria-orientation，那个属性它根本没输出 */
+  [data-scope='checkbox-group'][data-part='root'] {
+    display: flex;
+    gap: var(--xh-checkbox-group-gap, var(--xh-stack-gap-md));
+  }
+
+  /* 两种取值各写一条：连接层缺省给的是 vertical，但受控写 horizontal 时不能靠默认值兜底 */
+  [data-scope='checkbox-group'][data-part='root'][data-orientation='vertical'] {
+    flex-direction: column;
+    /* 条目按内容收宽。竖排下 flex 子项默认拉伸，点击区会一路延伸到文字右侧的空白处，
+       用户点在离文字很远的地方也能翻转选项 */
+    align-items: flex-start;
+  }
+
+  [data-scope='checkbox-group'][data-part='root'][data-orientation='horizontal'] {
+    flex-direction: row;
+    flex-wrap: wrap;
+    align-items: center;
+  }
+
+  [data-scope='checkbox-group'][data-part='label'] {
+    color: var(--xh-checkbox-group-label-fg, var(--xh-fg-muted));
+    font-size: var(--xh-checkbox-group-label-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-checkbox-group-label-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-none);
+  }
+
+  /* label 自己不带任何状态属性，整组禁用只写在 root 上，只能从 root 往下够 */
+  [data-scope='checkbox-group'][data-part='root'][data-disabled]
+    [data-scope='checkbox-group'][data-part='label'] {
+    color: var(--xh-checkbox-group-label-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* position 是给条目内那份视觉隐藏的原生输入当定位基准：连接层给它写死了 position:absolute，
+     这里不立基准的话，原生校验气泡会飘到页面上离该条目很远的地方 */
+  [data-scope='checkbox-group'][data-part='item'] {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--xh-checkbox-group-item-gap, var(--xh-control-gap-md));
+    border-radius: var(--xh-checkbox-group-item-radius, var(--xh-shape-control));
+    color: var(--xh-checkbox-group-item-fg, var(--xh-fg-default));
+    font-size: var(--xh-checkbox-group-item-font-size, var(--xh-text-label-size));
+    line-height: var(--xh-leading-none);
+    cursor: pointer;
+  }
+
+  [data-scope='checkbox-group'][data-part='item']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* 条目禁用一律走 aria-disabled（原生 disabled 会让它从键盘用户眼里消失），
+     所以样式只能读 data-disabled，写 :disabled 永远不命中 */
+  [data-scope='checkbox-group'][data-part='item'][data-disabled] {
+    color: var(--xh-checkbox-group-item-fg-disabled, var(--xh-fg-disabled));
+    cursor: not-allowed;
+    opacity: var(--xh-state-disabled-opacity);
+  }
+
+  /* 只读整组都改不动，但不是禁用：颜色照常，只把"可点"这个暗示收回来。
+     排掉禁用项是因为这条选择器权重高过上面那条，不排就会把 not-allowed 覆盖回 default */
+  [data-scope='checkbox-group'][data-part='root'][data-readonly]
+    [data-scope='checkbox-group'][data-part='item']:not([data-disabled]) {
+    cursor: default;
+  }
+
+  /* 全选格与条目格共用同一套盒子，并成一条规则写：分开写迟早只改到一半，两个方框就此走形。
+     尺寸与选中态照 checkbox 的 root 搬，同一份视觉语言在单体与集合里必须一致。
+     trigger 那格没有对应的角色节点（anatomy 到 trigger 为止），只能由伪元素补出来 */
+  [data-scope='checkbox-group'][data-part='item-control'],
+  [data-scope='checkbox-group'][data-part='trigger']::before {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-checkbox-group-control-size, 16px);
+    block-size: var(--xh-checkbox-group-control-size, 16px);
+    border: var(--xh-stroke-thin) solid var(--xh-checkbox-group-control-border, var(--xh-border-default));
+    border-radius: var(--xh-checkbox-group-control-radius, var(--xh-radius-sm));
+    background: var(--xh-checkbox-group-control-bg, var(--xh-bg-canvas));
+    color: var(--xh-checkbox-group-control-fg, var(--xh-fg-on-brand));
+    font-size: var(--xh-checkbox-group-control-font-size, 12px);
+    line-height: var(--xh-leading-none);
+    transition:
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* content 只能给伪元素，绝不能并进上面那条：content 落在普通元素上会顶掉它的全部子节点，
+     item-control 里作者写的图标就此消失 */
+  [data-scope='checkbox-group'][data-part='trigger']::before {
+    content: '';
+  }
+
+  /* 悬停只加深空方框的描边。已选中的那一格必须排除：这条选择器的权重高过下面那条填色规则，
+     不排除就会在悬停时把 brand 描边换回灰色，方框看起来"缺了一圈" */
+  [data-scope='checkbox-group'][data-part='item']:not([data-disabled]):hover
+    [data-scope='checkbox-group'][data-part='item-control']:not([data-state='checked']) {
+    border-color: var(--xh-checkbox-group-control-border-hover, var(--xh-border-strong));
+  }
+
+  /* 选中即填色：条目是二态，全选格三态里 all 与 some 都算"有值"，共用同一副填色 */
+  [data-scope='checkbox-group'][data-part='item-control'][data-state='checked'],
+  [data-scope='checkbox-group'][data-part='trigger']:is([data-state='all'], [data-state='some'])::before {
+    border-color: var(--xh-checkbox-group-control-border-checked, var(--xh-bg-brand));
+    background: var(--xh-checkbox-group-control-bg-checked, var(--xh-bg-brand));
+  }
+
+  /* 勾号由皮肤补，作者不必自己往 item-control 里塞字符 */
+  [data-scope='checkbox-group'][data-part='item-control'][data-state='checked']::before {
+    content: '✓';
+  }
+
+  /* 全选格的三态：all 打勾、some 打横杠、none 留空。
+     some 就是读屏听到的 aria-checked=mixed，两者同源，样式只认 data-state */
+  [data-scope='checkbox-group'][data-part='trigger'][data-state='all']::before {
+    content: '✓';
+  }
+
+  [data-scope='checkbox-group'][data-part='trigger'][data-state='some']::before {
+    content: '−';
+  }
+
+  /* 校验失败标在每个方框上：root 上的 data-invalid 是唯一出处，条目自己不带这个属性 */
+  [data-scope='checkbox-group'][data-part='root'][data-invalid]
+    [data-scope='checkbox-group'][data-part='item-control'] {
+    border-color: var(--xh-checkbox-group-control-border-invalid, var(--xh-color-danger-500));
+  }
+
+  [data-scope='checkbox-group'][data-part='item-text'] {
+    color: inherit;
+    user-select: none;
+  }
+
+  /* 全选格与条目同形，但字重加一档，读起来才不像又一个普通选项。
+     它是普通元素而非原生控件（三态只有非原生控件表达得出），禁用态同样只能读 data-disabled */
+  [data-scope='checkbox-group'][data-part='trigger'] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--xh-checkbox-group-trigger-gap, var(--xh-control-gap-md));
+    border-radius: var(--xh-checkbox-group-trigger-radius, var(--xh-shape-control));
+    color: var(--xh-checkbox-group-trigger-fg, var(--xh-fg-default));
+    font-size: var(--xh-checkbox-group-trigger-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-checkbox-group-trigger-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+    cursor: pointer;
+    user-select: none;
+  }
+
+  [data-scope='checkbox-group'][data-part='trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  [data-scope='checkbox-group'][data-part='trigger'][data-disabled] {
+    color: var(--xh-checkbox-group-trigger-fg-disabled, var(--xh-fg-disabled));
+    cursor: not-allowed;
+    opacity: var(--xh-state-disabled-opacity);
+  }
+
+  /* 只读与禁用会同时出现在 trigger 上（连接层两个属性各写各的），
+     同权重下后写的赢，所以这里必须显式排掉禁用，否则禁用的手势指示被只读盖掉 */
+  [data-scope='checkbox-group'][data-part='trigger'][data-readonly]:not([data-disabled]) {
+    cursor: default;
+  }
+
+  /* 表单出口：连接层已经把整套视觉隐藏写进内联 style（absolute + 1px + clip-path），
+     这里绝不能再补 display:none——那份输入必须留在布局里，原生校验提示要有处可贴。
+     只补一条不吃指针，免得它挡住条目的点击 */
+  [data-scope='checkbox-group'][data-part='item-hidden-input'] {
+    pointer-events: none;
+  }
+
+  /* 上面凡是给了 display 的角色节点都要补这条：display 声明会盖掉 UA 的 [hidden]{display:none}，
+     不补的话作者给节点加 hidden 后它照样显示 */
+  [data-scope='checkbox-group'][data-part='root'][hidden],
+  [data-scope='checkbox-group'][data-part='item'][hidden],
+  [data-scope='checkbox-group'][data-part='item-control'][hidden],
+  [data-scope='checkbox-group'][data-part='trigger'][hidden] {
+    display: none;
+  }
+}

package/css/checkbox.css

@@ -0,0 +1,91 @@
+@layer xihan.components {
+  [data-scope='checkbox'][data-part='root'] {
+    /* 尺寸档只换方框边长这一个私有槽，勾的字号按边长的比例跟着走；
+       指示器从 root 继承这两个槽，换档不必给每个部件各写一条选择器 */
+    --xh-_checkbox-box: var(--xh-space-4);
+    --xh-_checkbox-glyph: calc(var(--xh-_checkbox-box) * 0.75);
+
+    /* 选中态的底与描边随语气走。没写 data-tone 时 --xh-_tone 没被声明，退回原来的品牌色 */
+    --xh-_checkbox-accent: var(--xh-_tone, var(--xh-bg-brand));
+
+    /* 实心底上的勾与横杠，同样没写 data-tone 时退回原来的品牌底前景色 */
+    --xh-_checkbox-on-accent: var(--xh-_tone-on, var(--xh-fg-on-brand));
+
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-_checkbox-box);
+    block-size: var(--xh-_checkbox-box);
+    padding: 0;
+    border: 1px solid var(--xh-checkbox-border, var(--xh-border-default));
+    border-radius: var(--xh-radius-sm);
+    background: var(--xh-checkbox-bg, var(--xh-bg-canvas));
+    color: var(--xh-checkbox-fg, var(--xh-_checkbox-on-accent));
+    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);
+  }
+
+  /* 半选与全选同样是「有值」，方框都得填上：
+     只填全选的话，半选那条横杠是实心底上的前景色（白），压在白画布上等于没画 */
+  [data-scope='checkbox'][data-part='root'][data-state='checked'],
+  [data-scope='checkbox'][data-part='root'][data-state='indeterminate'] {
+    border-color: var(--xh-checkbox-border-checked, var(--xh-_checkbox-accent));
+    background: var(--xh-checkbox-bg-checked, var(--xh-_checkbox-accent));
+  }
+
+  [data-scope='checkbox'][data-part='root'][data-disabled] {
+    cursor: not-allowed;
+    opacity: var(--xh-state-disabled-opacity);
+  }
+
+  [data-scope='checkbox'][data-part='root']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  [data-scope='checkbox'][data-part='root'][data-size='sm'] {
+    --xh-_checkbox-box: var(--xh-space-3);
+  }
+
+  [data-scope='checkbox'][data-part='root'][data-size='lg'] {
+    --xh-_checkbox-box: var(--xh-space-5);
+  }
+
+  [data-scope='checkbox'][data-part='indicator'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 100%;
+    block-size: 100%;
+    line-height: var(--xh-leading-none);
+    font-size: var(--xh-_checkbox-glyph);
+  }
+
+  [data-scope='checkbox'][data-part='indicator']::before {
+    content: '✓';
+  }
+
+  [data-scope='checkbox'][data-part='indicator'][data-state='unchecked'] {
+    display: none;
+  }
+
+  /* 半选画一条横杠盖住勾：aria-checked=mixed 在视觉上也得与「全选」分得开 */
+  [data-scope='checkbox'][data-part='indicator'][data-state='indeterminate'] {
+    position: relative;
+    color: transparent;
+  }
+
+  [data-scope='checkbox'][data-part='indicator'][data-state='indeterminate']::after {
+    position: absolute;
+    inline-size: 60%;
+    block-size: var(--xh-stroke-thick);
+    border-radius: var(--xh-radius-full);
+    background: var(--xh-checkbox-indicator-fg, var(--xh-_checkbox-on-accent));
+    content: '';
+  }
+}