@xihan-ui/styles 1.0.0 → 2.0.0

package/css/color-slider.css

@@ -0,0 +1,274 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 color slider 样式。 */
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='color-slider'] {
+    --xh-color-slider-skin: 1;
+  }
+
+  /* 定位分工：拇指在**主轴**上的位置由连接层每帧写进内联样式——
+     水平是 inset-inline-start，竖直是 inset-block-end；轨道的渐变同样是连接层按当前颜色现算的内联值。
+     这份皮肤只管交叉轴的尺寸、拇指的描边与状态表现，以及透明度那一路垫在轨道底下的棋盘格。 */
+
+  /* 私有槽位：拇指直径与轨道厚度同时被 control / track / thumb 用到，收成两个槽位挂在 root 上，
+     尺寸档只改这两处，靠继承发到子部件。颜色带比普通滑杆的底槽厚：它画的是颜色本身，太细看不清走向 */
+  [data-scope='color-slider'][data-part='root'] {
+    --xh-_thumb-size: var(--xh-color-slider-thumb-size, var(--xh-track-thumb-size));
+    --xh-_track-thickness: var(--xh-color-slider-track-thickness, var(--xh-space-3));
+
+    display: flex;
+    flex-direction: column;
+    /* 字段标签贴控件（§6.4 复合单字段） */
+    gap: var(--xh-color-slider-gap, var(--xh-space-1));
+  }
+
+  /* 竖排时整条控件收成一块，不再撑满一行：宽度由拇指直径决定 */
+  [data-scope='color-slider'][data-part='root'][data-orientation='vertical'] {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  /* 禁用不整体压暗（§7.2 第 9 条）：标签是文字，换到禁用前景；颜色带与拇指画的是颜色本身，换不得色，
+     压暗只做一次、落在 control 上（track / thumb 各自再叠一层 opacity 会越叠越黑），拇指另收掉抬升 */
+
+  /* 字段标签：14 / 500 / fg-default（§6.4），禁用换到 --xh-fg-subtle */
+  [data-scope='color-slider'][data-part='label'] {
+    color: var(--xh-color-slider-label-fg, var(--xh-fg-default));
+    font-size: var(--xh-color-slider-label-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-color-slider-label-font-weight, var(--xh-text-label-weight));
+  }
+
+  [data-scope='color-slider'][data-part='label'][data-disabled] {
+    color: var(--xh-color-slider-label-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* 拇指以它为定位上下文（拇指常常浮出轨道，挂在 track 上会被轨道的盒子束住）。
+     厚度取拇指直径与轨道厚度里大的那个。touch-action 由连接层内联给，这里不写。 */
+  [data-scope='color-slider'][data-part='control'] {
+    position: relative;
+    display: flex;
+    align-items: center;
+    block-size: max(var(--xh-_thumb-size), var(--xh-_track-thickness));
+    cursor: pointer;
+  }
+
+  [data-scope='color-slider'][data-part='control'][data-orientation='vertical'] {
+    flex-direction: column;
+    justify-content: center;
+    inline-size: max(var(--xh-_thumb-size), var(--xh-_track-thickness));
+    block-size: var(--xh-color-slider-vertical-length, var(--xh-overlay-menu-min-w));
+  }
+
+  /* 按下轨道即跳，拖动中光标换成"抓着"的样子，手感与拇指一致 */
+  [data-scope='color-slider'][data-part='control'][data-dragging] {
+    cursor: grabbing;
+  }
+
+  [data-scope='color-slider'][data-part='control'][data-readonly]:not([data-disabled]) {
+    cursor: default;
+  }
+
+  [data-scope='color-slider'][data-part='control'][data-disabled] {
+    opacity: var(--xh-state-disabled-opacity);
+    cursor: not-allowed;
+  }
+
+  /* 轨道画的是颜色本身：渐变由连接层内联给，这里只给形状与一圈细边把浅色端从底色里框出来。
+     透明度那一路的棋盘格垫在轨道底下（background-color 与后面几层 background-image 是同一个盒），
+     内联的渐变写的是 background-image 的第一层——连接层只写这一个属性，不会把这里的层盖掉 */
+  [data-scope='color-slider'][data-part='track'] {
+    position: relative;
+    border-radius: var(--xh-color-slider-track-radius, var(--xh-shape-pill));
+    box-shadow: inset 0 0 0 var(--xh-stroke-thin) var(--xh-color-slider-track-border, var(--xh-border-subtle));
+  }
+
+  [data-scope='color-slider'][data-part='track'][data-orientation='horizontal'] {
+    inline-size: 100%;
+    block-size: var(--xh-_track-thickness);
+  }
+
+  [data-scope='color-slider'][data-part='track'][data-orientation='vertical'] {
+    block-size: 100%;
+    inline-size: var(--xh-_track-thickness);
+  }
+
+  /* 透明度那一路：轨道从全透明走到实色，透明那半正好把棋盘格露出来。
+     棋盘格铺在轨道自己身上而不是 control 上，圆角才裁得住。
+     注意连接层写的是 background-image（覆盖整个属性），所以格子走 background-color 加伪元素 */
+  [data-scope='color-slider'][data-part='track'][data-channel='alpha']::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    border-radius: inherit;
+    background-color: var(--xh-color-slider-checker-base, var(--xh-bg-surface));
+    background-image:
+      linear-gradient(45deg, var(--xh-color-slider-checker, var(--xh-color-neutral-300)) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--xh-color-slider-checker, var(--xh-color-neutral-300)) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--xh-color-slider-checker, var(--xh-color-neutral-300)) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--xh-color-slider-checker, var(--xh-color-neutral-300)) 75%);
+    background-position: 0 0, 0 4px, 4px -4px, -4px 0;
+    background-size: 8px 8px;
+  }
+
+  /* 伪元素要压在 z-index 之下，轨道得自己成一个层叠上下文 */
+  [data-scope='color-slider'][data-part='track'][data-channel='alpha'] {
+    isolation: isolate;
+  }
+
+  /* 圆点浮在轨道之上：轨道是流内的，拇指是绝对定位的，天然后来居上。
+     拇指填的是当前那一档的颜色（连接层写进私有槽），拇指是可拖起的 raised 面（§8）：
+     --xh-border-default 描边把它从任何底色里框出来，raised 影只是加成、不作边界。
+     box-sizing 必须显式写：描边要吃进直径里，否则下面按半个直径回拉的负外边距就对不上圆心。 */
+  [data-scope='color-slider'][data-part='thumb'] {
+    --xh-_color-slider-thumb-color: transparent;
+
+    position: absolute;
+    box-sizing: border-box;
+    inline-size: var(--xh-_thumb-size);
+    block-size: var(--xh-_thumb-size);
+    border: var(--xh-stroke-thick) solid var(--xh-color-slider-thumb-border, var(--xh-border-default));
+    border-radius: var(--xh-color-slider-thumb-radius, var(--xh-shape-circle));
+    background: var(--xh-color-slider-thumb-bg, var(--xh-_color-slider-thumb-color));
+    box-shadow: var(--xh-color-slider-thumb-shadow, var(--xh-elevation-raised));
+    cursor: grab;
+    transition:
+      scale var(--xh-motion-duration-micro) var(--xh-motion-ease-enter-strong),
+      box-shadow var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 内联样式把 inset-inline-start 定在值所在的比例上，那是拇指的**起始边**不是圆心；
+     用负的逻辑外边距回拉半个直径，圆心才落在比例点上（rtl 下负的逻辑外边距自己跟着换向）。 */
+  [data-scope='color-slider'][data-part='thumb'][data-orientation='horizontal'] {
+    inset-block-start: 50%;
+    margin-block-start: calc(var(--xh-_thumb-size) / -2);
+    margin-inline-start: calc(var(--xh-_thumb-size) / -2);
+  }
+
+  /* 竖排的主轴是 inset-block-end（值向上增大），回拉也就换到 block-end 那侧 */
+  [data-scope='color-slider'][data-part='thumb'][data-orientation='vertical'] {
+    inset-inline-start: 50%;
+    margin-inline-start: calc(var(--xh-_thumb-size) / -2);
+    margin-block-end: calc(var(--xh-_thumb-size) / -2);
+  }
+
+  /* 放大用 scale 而不是改尺寸：变换绕自身中心发生，圆心不动。海拔从 raised 换到 lifted */
+  [data-scope='color-slider'][data-part='thumb'][data-dragging] {
+    scale: var(--xh-color-slider-thumb-scale-dragging, var(--xh-motion-scale-drag));
+    cursor: grabbing;
+    box-shadow: var(--xh-color-slider-thumb-shadow-dragging, var(--xh-elevation-lifted));
+  }
+
+  /* 校验失败时描边换成无效色：拇指的面要保住当前颜色，只能动描边 */
+  [data-scope='color-slider'][data-part='thumb'][data-invalid] {
+    border-color: var(--xh-color-slider-thumb-border-invalid, var(--xh-border-invalid));
+  }
+
+  [data-scope='color-slider'][data-part='thumb'][data-readonly]:not([data-disabled]) {
+    cursor: default;
+  }
+
+  /* 禁用：拖不起来的东西不该看着像浮在轨道上，影收掉；面仍是当前颜色，压暗由 control 那一层给 */
+  [data-scope='color-slider'][data-part='thumb'][data-disabled] {
+    box-shadow: var(--xh-color-slider-thumb-shadow-disabled, none);
+    cursor: not-allowed;
+  }
+
+  /* 值气泡：挂在拇指里，跟着拇指一起走位。默认只在推动那一刻露面 */
+  [data-scope='color-slider'][data-part='value-text'] {
+    position: absolute;
+    inset-block-end: 100%;
+    inset-inline: 50%;
+    inline-size: max-content;
+    margin-block-end: var(--xh-color-slider-value-text-offset, var(--xh-space-2));
+    margin-inline: auto;
+    padding-block: var(--xh-color-slider-value-text-py, var(--xh-space-0_5));
+    padding-inline: var(--xh-color-slider-value-text-px, var(--xh-space-2));
+    border-radius: var(--xh-color-slider-value-text-radius, var(--xh-shape-control));
+    background: var(--xh-color-slider-value-text-bg, var(--xh-bg-brand));
+    color: var(--xh-color-slider-value-text-fg, var(--xh-fg-on-brand));
+    font-size: var(--xh-color-slider-value-text-font-size, var(--xh-text-caption-size));
+    font-variant-numeric: tabular-nums;
+    line-height: var(--xh-leading-normal);
+    white-space: nowrap;
+    /* 气泡贴在拇指上方，指针要落到拇指上，不能被它挡住 */
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='color-slider'][data-part='value-text'][hidden] {
+    display: none;
+  }
+
+  [data-scope='color-slider'][data-part='value-text'][data-dragging] {
+    opacity: 1;
+  }
+
+  /* 竖排轨道的气泡挪到行侧：压在拇指上方会挡住上一档的值 */
+  [data-scope='color-slider'][data-part='value-text'][data-orientation='vertical'] {
+    inset-block: 50%;
+    inset-inline: 100% auto;
+    block-size: max-content;
+    margin-block: auto;
+    margin-inline: var(--xh-color-slider-value-text-offset, var(--xh-space-2)) 0;
+  }
+
+  /* —— 尺寸 —— */
+  /* 尺寸只改 root 上那两个槽位，control / track / thumb 跟着一起走；中间档不写规则，缺省即中档 */
+  [data-scope='color-slider'][data-part='root'][data-size='sm'] {
+    --xh-_thumb-size: var(--xh-color-slider-thumb-size, var(--xh-space-3));
+    --xh-_track-thickness: var(--xh-color-slider-track-thickness, var(--xh-space-2));
+  }
+
+  [data-scope='color-slider'][data-part='root'][data-size='lg'] {
+    --xh-_thumb-size: var(--xh-color-slider-thumb-size, var(--xh-space-6));
+    --xh-_track-thickness: var(--xh-color-slider-track-thickness, var(--xh-space-4));
+  }
+
+  /* display 会盖掉 UA 的 [hidden]{display:none}，凡是被赋了 display 的角色节点都要显式让位 */
+  [data-scope='color-slider'][data-part='root'][hidden],
+  [data-scope='color-slider'][data-part='control'][hidden] {
+    display: none;
+  }
+
+  /* hidden-input 是 type=hidden 的原生输入，浏览器本就不渲染它，这里一条声明都不给。 */
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-scope='color-slider'][data-part='thumb'],
+    [data-scope='color-slider'][data-part='value-text'] {
+      transition: none;
+    }
+  }
+
+  /*
+   * 高对比档：轨道画的就是颜色本身，被系统换掉之后整条滑杆不再能调色。
+   * 轨道与拇指退出强制着色保住原色，各补一圈系统描边把它们从背景里框出来。
+   */
+  @media (forced-colors: active) {
+    [data-scope='color-slider'][data-part='track'],
+    [data-scope='color-slider'][data-part='track']::before,
+    [data-scope='color-slider'][data-part='thumb'] {
+      forced-color-adjust: none;
+    }
+
+    [data-scope='color-slider'][data-part='track'] {
+      outline: var(--xh-stroke-thin) solid CanvasText;
+      outline-offset: calc(-1 * var(--xh-stroke-thin));
+    }
+
+    [data-scope='color-slider'][data-part='thumb'] {
+      border-color: CanvasText;
+    }
+
+    [data-scope='color-slider'][data-part='thumb']:focus-visible {
+      outline: var(--xh-ring-width) solid Highlight;
+      outline-offset: var(--xh-ring-offset);
+    }
+  }
+}

package/css/color-swatch-picker.css

@@ -0,0 +1,243 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 color swatch picker 样式。 */
+
+@import '../family/swatch.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='color-swatch-picker'] {
+    --xh-color-swatch-picker-skin: 1;
+  }
+
+  /* 一组固定颜色排成可换行的网格，每格是一颗 role=radio 的方块。
+     格子的边长跟着控件行高走（sm/md/lg 三档），一排色块与旁边的按钮、字段齐高；
+     色块面、棋盘格与描边由 Swatch 家族画，这份皮肤只管格子的命中区、选中描边与选中徽标 */
+  [data-scope='color-swatch-picker'][data-part='root'] {
+    /* 尺寸档只换这几个私有槽，格子与标记都从 root 继承它们；标题走字段标签角色，不随档 */
+    --xh-_color-swatch-picker-cell: var(--xh-control-h-md);
+    --xh-_color-swatch-picker-gap: var(--xh-control-gap-md);
+    --xh-_color-swatch-picker-indicator: var(--xh-control-indicator-md);
+    /* 勾从徽标里减去一圈内衬，徽标换档时勾跟着走 */
+    --xh-_color-swatch-picker-mark: calc(var(--xh-_color-swatch-picker-indicator) - var(--xh-space-1));
+    /* 徽标底随语气走。没写 data-tone 时 --xh-_tone 没被声明，退回品牌色 */
+    --xh-_color-swatch-picker-accent: var(--xh-_tone, var(--xh-bg-brand));
+    /* 作者往标记槽里换 XhIcon 时与兜底的勾同一把尺 */
+    --xh-icon-size: var(--xh-color-swatch-picker-icon-size, var(--xh-_color-swatch-picker-mark));
+
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--xh-color-swatch-picker-gap, var(--xh-_color-swatch-picker-gap));
+  }
+
+  [data-scope='color-swatch-picker'][data-part='root'][data-disabled] {
+    cursor: not-allowed;
+  }
+
+  /* —— 尺寸 —— */
+  [data-scope='color-swatch-picker'][data-part='root'][data-size='sm'] {
+    --xh-_color-swatch-picker-cell: var(--xh-control-h-sm);
+    --xh-_color-swatch-picker-gap: var(--xh-control-gap-sm);
+    --xh-_color-swatch-picker-indicator: var(--xh-control-indicator-sm);
+  }
+
+  [data-scope='color-swatch-picker'][data-part='root'][data-size='lg'] {
+    --xh-_color-swatch-picker-cell: var(--xh-control-h-lg);
+    --xh-_color-swatch-picker-gap: var(--xh-control-gap-lg);
+    --xh-_color-swatch-picker-indicator: var(--xh-control-indicator-lg);
+  }
+
+  /* 标题独占一行，格子从下一行起排。复合单字段的标签（§6.4）：14 / 500 / fg-default，不随档；
+     与格子的距离贴控件 space-1——容器的 gap 归格子之间，标签在它之上补一段差值把距离收成目标值 */
+  [data-scope='color-swatch-picker'][data-part='label'] {
+    flex-basis: 100%;
+    margin-block-end: calc(
+      var(--xh-color-swatch-picker-label-gap, var(--xh-space-1))
+      - var(--xh-color-swatch-picker-gap, var(--xh-_color-swatch-picker-gap))
+    );
+    color: var(--xh-color-swatch-picker-label-fg, var(--xh-fg-default));
+    font-size: var(--xh-color-swatch-picker-label-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-color-swatch-picker-label-font-weight, var(--xh-text-label-weight));
+  }
+
+  [data-scope='color-swatch-picker'][data-part='label'][data-disabled] {
+    color: var(--xh-color-swatch-picker-label-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* 一格：正方形命中区，里面铺满色块面。
+     position 是给格内那份视觉隐藏的原生输入与压在色块上的标记做定位基准，别去掉。
+     色块的描边按格子的状态换（静息 / 悬停 / 按下 / 选中），四档都写在格子这一层的私有槽上，
+     色块面那条只读它——这一格的底色就是它要展示的那个颜色，交互回执只能落在描边上 */
+  [data-scope='color-swatch-picker'][data-part='item'] {
+    --xh-_color-swatch-picker-edge: var(--xh-color-swatch-picker-swatch-border, var(--xh-border-default));
+
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    inline-size: var(--xh-color-swatch-picker-item-size, var(--xh-_color-swatch-picker-cell));
+    block-size: var(--xh-color-swatch-picker-item-size, var(--xh-_color-swatch-picker-cell));
+    /* 色块 item 的身份是 inset（§6.3：嵌在 control 内的小块） */
+    border-radius: var(--xh-color-swatch-picker-item-radius, var(--xh-shape-inset));
+    outline: none;
+    cursor: pointer;
+    transition: scale var(--xh-motion-duration-release) var(--xh-motion-ease-release);
+  }
+
+  /* 指到哪一格：描边换到控件的悬停边（border-strong 只留给 contrast-more 与登记的强调边）；
+     选中的那一格保留自己的品牌描边（§9.3 选中身份不被悬停盖掉） */
+  [data-scope='color-swatch-picker'][data-part='item']:not([data-disabled], [data-readonly], [data-state='checked']):hover {
+    --xh-_color-swatch-picker-edge: var(--xh-color-swatch-picker-swatch-border-hover, var(--xh-border-control-hover));
+  }
+
+  /* 这一格的底色就是它要展示的那个颜色，换底等于把展示物盖掉（§9.1 的「同时换底」在这里落不下去），
+     交互回执只能落在别处：按下去看下压，描边同时换到品牌色作第二通道（按住即将选中的那一格）。
+     置灰与只读的都不压；指针 :active 与 Headless 投影的 data-pressed 看见同一副按压面 */
+  [data-scope='color-swatch-picker'][data-part='item']:not([data-disabled], [data-readonly]):is(:active, [data-pressed]) {
+    --xh-_color-swatch-picker-edge: var(--xh-color-swatch-picker-swatch-border-pressed, var(--xh-_tone, var(--xh-fg-brand)));
+
+    scale: var(--xh-motion-scale-press);
+    transition-duration: var(--xh-motion-duration-press);
+    transition-timing-function: var(--xh-motion-ease-press);
+  }
+
+  /* 正被选中的那一格：色块自己的描边换成品牌色（语气组取语气色），与正中的徽标一起表达选中，
+     不再在盒子外面另画一圈——外圈 outline 留给焦点环独占 */
+  [data-scope='color-swatch-picker'][data-part='item'][data-state='checked'] {
+    --xh-_color-swatch-picker-edge: var(--xh-color-swatch-picker-ring, var(--xh-_tone, var(--xh-fg-brand)));
+  }
+
+  /* 焦点环独占 outline：选中不再画外圈，由色块正中的徽标与色块自己的品牌描边表达 */
+  [data-scope='color-swatch-picker'][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 表达 */
+  [data-scope='color-swatch-picker'][data-part='item'][data-disabled] {
+    cursor: not-allowed;
+    opacity: var(--xh-state-disabled-opacity);
+  }
+
+  /* 只读整组都改不动，但不是禁用：颜色照常，只把"可点"这个暗示收回来。
+     排掉禁用项是因为这条选择器权重高过上面那条，不排就会把 not-allowed 覆盖回 default */
+  [data-scope='color-swatch-picker'][data-part='item'][data-readonly]:not([data-disabled]) {
+    cursor: default;
+  }
+
+  /* 色块面铺满格子，圆角随格子；家族合同里的三把尺在这里接上组件自己的公开槽，
+     描边读格子按状态给的那一档 */
+  [data-scope='color-swatch-picker'][data-part='swatch'] {
+    --xh-swatch-size: 100%;
+    --xh-swatch-radius: var(--xh-color-swatch-picker-item-radius, var(--xh-shape-inset));
+    --xh-swatch-border: var(--xh-_color-swatch-picker-edge);
+
+    transition: border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 校验失败：整组的描边转警示色，压过悬停、按下与选中那几档 */
+  [data-scope='color-swatch-picker'][data-part='swatch'][data-invalid] {
+    --xh-swatch-border: var(--xh-color-swatch-picker-swatch-border-invalid, var(--xh-border-invalid));
+  }
+
+  /* 选中徽标：压在色块正中的一枚小圆徽——语气底加一圈画布色描边，
+     再往里是一个勾。徽标自带底色与描边，落在任何颜色的色块上都看得出来，
+     色块恰好是品牌色时那圈画布色把它从底上隔出来 */
+  [data-scope='color-swatch-picker'][data-part='indicator'] {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    pointer-events: none;
+  }
+
+  /* 徽标本体画在 ::before 上，勾画在 ::after 上；作者往部件里塞自己的图形时只有勾让位 */
+  [data-scope='color-swatch-picker'][data-part='indicator']::before {
+    content: '';
+    position: absolute;
+    inline-size: var(--xh-color-swatch-picker-indicator-size, var(--xh-_color-swatch-picker-indicator));
+    block-size: var(--xh-color-swatch-picker-indicator-size, var(--xh-_color-swatch-picker-indicator));
+    border: var(--xh-stroke-thin) solid var(--xh-color-swatch-picker-indicator-border, var(--xh-bg-canvas));
+    /* 正方盒取 circle（§6.3：宽高同槽的盒不得用 pill 冒充圆） */
+    border-radius: var(--xh-shape-circle);
+    background: var(--xh-color-swatch-picker-indicator-bg, var(--xh-_color-swatch-picker-accent));
+    opacity: 0;
+    scale: 0;
+    transition:
+      opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      scale var(--xh-motion-duration-micro) var(--xh-motion-ease-settle);
+  }
+
+  /* 没写内容就由皮肤画勾；作者往部件里塞了自己的图形，这条规则即不命中 */
+  [data-scope='color-swatch-picker'][data-part='indicator']:empty::after {
+    content: '';
+    position: relative;
+    inline-size: var(--xh-icon-size, var(--xh-_color-swatch-picker-mark));
+    block-size: var(--xh-icon-size, var(--xh-_color-swatch-picker-mark));
+    background-color: var(--xh-color-swatch-picker-indicator-fg, var(--xh-_tone-on, var(--xh-fg-on-brand)));
+    -webkit-mask: var(--xh-glyph-mark-check) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-check) center / contain no-repeat;
+    opacity: 0;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 作者塞进来的图形跟着勾同一套显隐 */
+  [data-scope='color-swatch-picker'][data-part='indicator'] > * {
+    position: relative;
+    color: var(--xh-color-swatch-picker-indicator-fg, var(--xh-_tone-on, var(--xh-fg-on-brand)));
+    opacity: 0;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 徽标出现时略微涨过 1 再收回，过冲量落在格内不碰描边 */
+  [data-scope='color-swatch-picker'][data-part='indicator'][data-state='checked']::before {
+    opacity: 1;
+    scale: 1;
+  }
+
+  [data-scope='color-swatch-picker'][data-part='indicator'][data-state='checked']:empty::after,
+  [data-scope='color-swatch-picker'][data-part='indicator'][data-state='checked'] > * {
+    opacity: 1;
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  [data-scope='color-swatch-picker'][data-part='root'][hidden],
+  [data-scope='color-swatch-picker'][data-part='label'][hidden],
+  [data-scope='color-swatch-picker'][data-part='item'][hidden],
+  [data-scope='color-swatch-picker'][data-part='indicator'][hidden] {
+    display: none;
+  }
+
+  @media print {
+    /* 打印默认丢底色：徽标那块语气底落到纸上会消失，勾就悬在色块上没了衬底。
+       徽标改画成一圈实边——边框印得出来，直径与圆心都不动（描边吃进盒里） */
+    [data-scope='color-swatch-picker'][data-part='indicator'][data-state='checked']::before {
+      border: var(--xh-stroke-thick) solid currentColor;
+    }
+  }
+
+  /*
+   * 高对比档：色块面由家族退出强制着色自己保住原色；选中描边与徽标换成系统的高亮色，
+   * 徽标那圈描边与勾各取系统墨色，选中的那一格在任何色块上都框得出来。
+   */
+  @media (forced-colors: active) {
+    /* 家族在这一档把色块描边统一钉成 CanvasText，选中的那一格要在它之上换成高亮色 */
+    [data-scope='color-swatch-picker'][data-part='item'][data-state='checked'] > [data-part='swatch'] {
+      border-color: Highlight;
+    }
+
+    [data-scope='color-swatch-picker'][data-part='indicator']::before {
+      border-color: Canvas;
+      background: Highlight;
+    }
+
+    [data-scope='color-swatch-picker'][data-part='indicator']:empty::after {
+      background-color: HighlightText;
+    }
+  }
+}

package/css/color-swatch.css

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 color swatch 样式。 */
+
+@import '../family/swatch.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='color-swatch'] {
+    --xh-color-swatch-skin: 1;
+  }
+
+  /* 面、棋盘格、描边与尺寸档全由色块面家族画（root 带 data-xh-swatch）；
+     组件层只把自己的公开槽映射到家族合同，并给行内排版补一个基线对齐。
+     棋盘格的两色是家族层的事（--xh-swatch-checker / --xh-swatch-checker-base），画的是「透明」本身，不随组件换 */
+  [data-scope='color-swatch'][data-part='root'] {
+    --xh-swatch-size: var(--xh-color-swatch-size, var(--xh-_swatch-size));
+    --xh-swatch-radius: var(--xh-color-swatch-radius, var(--xh-shape-inset));
+    --xh-swatch-border: var(--xh-color-swatch-border, var(--xh-border-default));
+
+    vertical-align: middle;
+  }
+
+  /* 解析不出的颜色只剩棋盘格：描边换成危险色，看得出这里本该有个颜色 */
+  [data-scope='color-swatch'][data-part='root'][data-invalid] {
+    --xh-swatch-border: var(--xh-color-swatch-border-invalid, var(--xh-border-invalid));
+  }
+
+  [data-scope='color-swatch'][data-part='root'][hidden] {
+    display: none;
+  }
+}