@xihan-ui/styles 1.0.0 → 2.0.0

package/css/heatmap.css

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 heatmap 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='heatmap'] {
@@ -18,9 +25,8 @@
        不接控件高度那把尺——它是给可点可输的控件在一行里排齐用的，矩阵格子不可交互，
        接上去密度档一换矩阵就跟着变形 */
     --xh-_heatmap-row-h: var(--xh-heatmap-row-h, var(--xh-space-5));
-    /* 格间距等于聚焦环占的宽度（偏移 + 环宽）：环因此整圈落在格子之间的空当里，
-       不压到相邻的格子上（外缘与相邻格相接） */
-    --xh-_heatmap-gap: calc(var(--xh-ring-offset) + var(--xh-ring-width));
+    /* 格与格之间的空当：格子按天铺满一年，靠这道缝把一格与相邻格分开 */
+    --xh-_heatmap-gap: var(--xh-space-1);
     --xh-_heatmap-gutter: var(--xh-heatmap-gutter, var(--xh-space-8));
     --xh-_heatmap-font-size: var(--xh-text-caption-size);
     /* 星期名隔行画：第 0/2/4/6 行那个字的颜色。缺省透明——只是字不上色，
@@ -43,9 +49,9 @@
     display: flex;
     flex-direction: column;
     gap: var(--xh-heatmap-gap, var(--xh-space-2));
-    /* 一整年五十几列，一屏放不下就自己横着滚。横向滚动会把纵向也变成 auto，
-       上下留出一圈聚焦环的余量，最上一行与最下一行的环才不会被裁掉 */
-    padding-block: var(--xh-heatmap-py, calc(var(--xh-ring-offset) + var(--xh-ring-width)));
+    /* 一整年五十几列，一屏放不下就自己横着滚。上下各留一道与格间距同宽的空当，
+       最上一行与最下一行不贴着滚动容器的边 */
+    padding-block: var(--xh-heatmap-py, var(--xh-_heatmap-gap));
     overflow-x: auto;
     /* 键盘走到视口外的格子时 scrollIntoView 会把它滚进来，落点要让开钉住的那一列，
        否则往回走的那一格正好停在行首星期名底下 */
@@ -121,13 +127,6 @@
     gap: var(--xh-heatmap-grid-gap, var(--xh-_heatmap-gap));
   }
 
-  /* 网格自己只在没有格子可落焦点时才占 Tab 位，那几帧里也该看得出焦点在哪。
-     环往内收：网格铺满 root，root 那层 overflow-x: auto 会把画在外沿的环裁掉 */
-  [data-scope='heatmap'][data-part='grid']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: calc(-1 * var(--xh-ring-width));
-  }
-
   [data-scope='heatmap'][data-part='row'] {
     /* 行首空出的列数由连接层写进这个槽：日历形态是区间起点不在周首日时的错列，
        月历形态是这一周里 1 号之前的那几个星期几 */
@@ -152,7 +151,7 @@
   /* 行首的星期名。月份行行首那个占位也是它，宽度一样，月份才对得上列。
      一整年放不下时网格横着滚，这一列钉在滚动容器的起始缘：跟着滚走的话，
      滚过头一屏就再也认不出哪一行是星期几。底色必须实色，格子从它下面滚过去不能透出来 */
-  [data-scope='heatmap'][data-part='week-day-label'] {
+  [data-scope='heatmap'][data-part='week-day'] {
     position: sticky;
     /* 层号收在 root 建的层叠上下文里，只跟组件内的兄弟比 */
     z-index: var(--xh-heatmap-sticky-layer, 1);
@@ -173,10 +172,10 @@
      一行只有 10px 高，七个 12px 的字挨着写会上下叠在一起；隔一行之后每个留下来的字
      有两行的高度（2 × 格高 + 格距）可用。哪一行是星期几由行自己的可及名字念出来，
      可见文字与可及名字是两件事，读屏这边一行都没少 */
-  [data-scope='heatmap'][data-part='week-day-label'][data-week-day='0'],
-  [data-scope='heatmap'][data-part='week-day-label'][data-week-day='2'],
-  [data-scope='heatmap'][data-part='week-day-label'][data-week-day='4'],
-  [data-scope='heatmap'][data-part='week-day-label'][data-week-day='6'] {
+  [data-scope='heatmap'][data-part='week-day'][data-week-day='0'],
+  [data-scope='heatmap'][data-part='week-day'][data-week-day='2'],
+  [data-scope='heatmap'][data-part='week-day'][data-week-day='4'],
+  [data-scope='heatmap'][data-part='week-day'][data-week-day='6'] {
     color: var(--xh-_heatmap-week-day-skip);
   }
 
@@ -217,17 +216,12 @@
      左侧那一列星期名就变成锯齿。两条选择器合起来正好是「本行第一个格子」，
      行里写不写星期名都成立 */
   [data-scope='heatmap'][data-part='row'] > [data-scope='heatmap'][data-part='cell']:first-child,
-  [data-scope='heatmap'][data-part='week-day-label'] + [data-scope='heatmap'][data-part='cell'] {
+  [data-scope='heatmap'][data-part='week-day'] + [data-scope='heatmap'][data-part='cell'] {
     margin-inline-start: calc(
       var(--xh-_heatmap-row-offset) * (var(--xh-_heatmap-cell-size) + var(--xh-_heatmap-gap))
     );
   }
 
-  [data-scope='heatmap'][data-part='cell']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
-  }
-
   /* —— 月历形态：一个自然月一块，块内一行是一周、一列是一个星期几 —— */
   [data-scope='heatmap'][data-part='root'][data-variant='month'] [data-scope='heatmap'][data-part='grid'] {
     flex-flow: row wrap;
@@ -257,7 +251,7 @@
   /* 块里的星期名是一排列头，宽度改成格宽才对得上下面的格子，也不再钉住。
      字比一格宽，不裁：裁掉就是七个缺角的字，让它往两边的列间距里溢出去，
      相邻两个各溢出一点也还差着一段空白 */
-  [data-scope='heatmap'][data-part='root'][data-variant='month'] [data-scope='heatmap'][data-part='week-day-label'] {
+  [data-scope='heatmap'][data-part='root'][data-variant='month'] [data-scope='heatmap'][data-part='week-day'] {
     position: static;
     inline-size: var(--xh-_heatmap-cell-size);
     overflow: visible;
@@ -329,12 +323,16 @@
     padding-block: var(--xh-heatmap-tooltip-py, var(--xh-space-1));
     padding-inline: var(--xh-heatmap-tooltip-px, var(--xh-space-2));
     border-radius: var(--xh-heatmap-tooltip-radius, var(--xh-shape-control));
+    /* 与 Tooltip 同一副反白气泡：任何浮层都得有一圈非透明描边（§8.4），描边从字色里兑两成，
+       深浅主题与语气换色时跟着字色走；影走 frosted 紧凑档，与 Tooltip 的 content 同深 */
+    border: var(--xh-stroke-thin) solid var(--xh-heatmap-tooltip-border, color-mix(in oklab, var(--xh-heatmap-tooltip-fg, var(--xh-bg-surface)) 20%, transparent));
     background: var(--xh-heatmap-tooltip-bg, var(--xh-fg-default));
     color: var(--xh-heatmap-tooltip-fg, var(--xh-bg-surface));
-    font-size: var(--xh-heatmap-tooltip-font-size, var(--xh-text-caption-size));
+    /* 字号与 Tooltip 缺省档同一把尺（次级标注档 13px） */
+    font-size: var(--xh-heatmap-tooltip-font-size, var(--xh-control-caption-md));
     line-height: var(--xh-leading-normal);
     white-space: nowrap;
-    box-shadow: var(--xh-heatmap-tooltip-shadow, var(--xh-elevation-floating));
+    box-shadow: var(--xh-heatmap-tooltip-shadow, var(--xh-material-frosted-compact-shadow));
     /* 详情条不接指针：压在格子上时指针要能穿过去，否则一进条里就算离开了格子，
        详情自己把自己收起来，来回闪 */
     pointer-events: none;
@@ -392,14 +390,19 @@
     box-shadow: inset 0 0 0 var(--xh-stroke-thin) var(--xh-heatmap-cell-border, var(--xh-border-default));
   }
 
+  /* 详情条的收起态：没有哪一格是活的时候整条藏起来 */
+  [data-scope='heatmap'][data-part='tooltip'][data-state='hidden'] {
+    display: none;
+  }
+
   /* 给了 display 的角色节点必须补这条：display 声明会盖掉 UA 的 [hidden]{display:none}，
-     不补的话作者给节点加 hidden 后它照样显示。详情条收起靠的正是这一条。
+     不补的话作者给节点加 hidden 后它照样显示。
      格子没有声明 display，UA 那条兜得住，不必列在这里 */
   [data-scope='heatmap'][data-part='root'][hidden],
   [data-scope='heatmap'][data-part='grid'][hidden],
   [data-scope='heatmap'][data-part='month-block'][hidden],
   [data-scope='heatmap'][data-part='row'][hidden],
-  [data-scope='heatmap'][data-part='week-day-label'][hidden],
+  [data-scope='heatmap'][data-part='week-day'][hidden],
   [data-scope='heatmap'][data-part='month-label'][hidden],
   [data-scope='heatmap'][data-part='row-label'][hidden],
   [data-scope='heatmap'][data-part='column-label'][hidden],
@@ -408,4 +411,59 @@
   [data-scope='heatmap'][data-part='legend-item'][hidden] {
     display: none;
   }
+
+  /*
+   * 打印：格子的深浅只写在底色上，纸上多数丢背景，整张图印成一片空白。
+   * 这一档把档位改画成边框的粗细——0 档只有一圈发丝线，档位越高边越厚，
+   * 顶到一半格宽时整格填满。边算在尺寸里（reset 兜了 border-box），格子大小一点不变。
+   *
+   * 比例取 0.2 / 0.3 / 0.4 / 0.5：缺省格宽 10px 下正好落在 2 / 3 / 4 / 5 像素，
+   * 与 0 档那一像素合成五档整数宽——边宽在屏幕与纸上都取整，分数宽会有两档并到一起。
+   *
+   * 第一条给的是高档那一身，下面四条按档位逐个改薄：档数由作者定，
+   * 超出缺省五档的那些落在第一条上，一律按最高档画。
+   * 图例里那几个方块与格子同源，跟着走同一套。
+   */
+  @media print {
+    [data-scope='heatmap'][data-part='cell'],
+    [data-scope='heatmap'][data-part='legend-item'] {
+      --xh-_heatmap-ink-ring: calc(var(--xh-_heatmap-cell-size) * 0.5);
+
+      border: var(--xh-_heatmap-ink-ring) solid currentColor;
+    }
+
+    [data-scope='heatmap'][data-part='cell'][data-level='0'],
+    [data-scope='heatmap'][data-part='legend-item'][data-level='0'] {
+      --xh-_heatmap-ink-ring: var(--xh-stroke-thin);
+    }
+
+    [data-scope='heatmap'][data-part='cell'][data-level='1'],
+    [data-scope='heatmap'][data-part='legend-item'][data-level='1'] {
+      --xh-_heatmap-ink-ring: calc(var(--xh-_heatmap-cell-size) * 0.2);
+    }
+
+    [data-scope='heatmap'][data-part='cell'][data-level='2'],
+    [data-scope='heatmap'][data-part='legend-item'][data-level='2'] {
+      --xh-_heatmap-ink-ring: calc(var(--xh-_heatmap-cell-size) * 0.3);
+    }
+
+    [data-scope='heatmap'][data-part='cell'][data-level='3'],
+    [data-scope='heatmap'][data-part='legend-item'][data-level='3'] {
+      --xh-_heatmap-ink-ring: calc(var(--xh-_heatmap-cell-size) * 0.4);
+    }
+  }
+
+  /*
+   * 高对比档：格子画的就是色阶本身，被系统换成同一个底色之后整张图没有任何深浅。
+   * 这几处退出强制着色，自己保住色阶；退出之后不再跟系统底色走，
+   * 各补一圈系统描边把方格从背景里框出来（原来那圈发丝线写在 inset 阴影上，这一档里被丢弃）。
+   */
+  @media (forced-colors: active) {
+    [data-scope='heatmap'][data-part='cell'],
+    [data-scope='heatmap'][data-part='legend-item'] {
+      forced-color-adjust: none;
+      outline: var(--xh-stroke-thin) solid CanvasText;
+      outline-offset: calc(-1 * var(--xh-stroke-thin));
+    }
+  }
 }

package/css/highlight.css

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 highlight 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='highlight'] {
@@ -11,16 +18,24 @@
   }
 
   /* 浏览器给 mark 的默认底色是一个固定的亮黄，暗色主题下压在深底上刺眼、
-     配的黑字也不随主题走；这里整份换成随主题走的品牌淡底 */
+     配的黑字也不随主题走；这里整份换成随主题走的品牌淡底。
+     槽名带 mark 段与部件对上 */
   [data-scope='highlight'][data-part='mark'] {
     padding-inline: var(--xh-highlight-mark-px, var(--xh-space-0_5));
-    border-radius: var(--xh-highlight-radius, var(--xh-shape-inset));
-    background: var(--xh-highlight-bg, var(--xh-bg-brand-subtle));
-    color: var(--xh-highlight-fg, var(--xh-fg-brand-strong));
-    font-weight: var(--xh-font-weight-medium);
+    border-radius: var(--xh-highlight-mark-radius, var(--xh-shape-inset));
+    background: var(--xh-highlight-mark-bg, var(--xh-bg-brand-subtle));
+    color: var(--xh-highlight-mark-fg, var(--xh-fg-brand-strong));
+    font-weight: var(--xh-highlight-mark-font-weight, var(--xh-font-weight-medium));
     /* 命中片段跨行时两半各自收边，否则圆角与内边距只画在整段的首尾。
        两条都写：WebKit 只认带前缀那条 */
     -webkit-box-decoration-break: clone;
     box-decoration-break: clone;
   }
+
+  /* 语气落在根上而不是每个 mark 上：命中片段有好几个，用哪族颜色是整段的属性。
+     使用者槽排在语气之前：写死了 mark 的底与字色，六族语气一并让位 */
+  [data-scope='highlight'][data-part='root'][data-tone] [data-part='mark'] {
+    background: var(--xh-highlight-mark-bg, var(--xh-_tone-subtle));
+    color: var(--xh-highlight-mark-fg, var(--xh-_tone-fg));
+  }
 }

package/css/hover-card.css

@@ -1,29 +1,12 @@
-@layer xihan.motion {
-  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
-     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
-  @keyframes xh-pop-in {
-    from {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
 
-    to {
-      opacity: 1;
-      scale: 1;
-    }
-  }
-  @keyframes xh-pop-out {
-    from {
-      opacity: 1;
-      scale: 1;
-    }
+/* 定义 hover card 样式。 */
 
-    to {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
-  }
-}
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
 
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
@@ -56,9 +39,10 @@
     display: none;
   }
 
-  [data-scope='hover-card'][data-part='trigger']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
+  /* 这里的 data-disabled 关掉的是卡片，不是宿主控件：光标仍旧交给宿主 */
+  [data-scope='hover-card'][data-part='root'][data-disabled],
+  [data-scope='hover-card'][data-part='trigger'][data-disabled] {
+    cursor: inherit;
   }
 
   /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
@@ -66,12 +50,15 @@
     /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，内容层继承它限高；
        引擎没算（尚未落位 / 无引擎 / 贴边归零）时不额外限高 */
     --xh-_hover-card-available-h: 100vh;
+    /* 落定那一侧的可用宽度，同样由定位引擎经内联自定义属性写进来，行内轴据此夹取；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时退到视口宽 */
+    --xh-_hover-card-available-w: 100vw;
 
     /* 卡片内容的自绘条浮在内容之上：轨道不上底色，实色轨道会在卡片右缘糊一条竖灰带 */
     --xh-scrollbar-track-bg: transparent;
 
     position: fixed;
-    z-index: var(--xh-hover-card-layer, var(--xh-layer-popover));
+    z-index: var(--xh-hover-card-layer, var(--xh-_layer, var(--xh-layer-popover)));
     /* 空壳不吃指针：trigger 与 content 之间那段间隙要能点得穿，
        指针穿行的判定全靠 content 自己的进出事件 */
     pointer-events: none;
@@ -82,13 +69,35 @@
     visibility: hidden;
   }
 
+  /* 缩放原点与进场位移按落定的那一侧给：卡片从贴着锚点的那条边涨开、沿主轴退让一小段。
+     两个槽由 content 继承。placement 是物理方向（引擎按 top / right / bottom / left 出值），
+     origin 与 translate 也是物理量，两边同轴，不随书写方向翻 */
+  [data-scope='hover-card'][data-part='positioner'][data-placement^='top'] {
+    --xh-_overlay-origin-y: 100%;
+    --xh-_overlay-enter-down: 1;
+  }
+
+  [data-scope='hover-card'][data-part='positioner'][data-placement^='bottom'] {
+    --xh-_overlay-origin-y: 0;
+    --xh-_overlay-enter-up: 1;
+  }
+
+  [data-scope='hover-card'][data-part='positioner'][data-placement^='left'] {
+    --xh-_overlay-origin-x: 100%;
+    --xh-_overlay-enter-right: 1;
+  }
+
+  [data-scope='hover-card'][data-part='positioner'][data-placement^='right'] {
+    --xh-_overlay-origin-x: 0;
+    --xh-_overlay-enter-left: 1;
+  }
+
   /* 与 tooltip 不同：卡片本体承载交互，必须吃指针——
      指针停在卡片上就不该收起，里面的链接与按钮也要点得到 */
   [data-scope='hover-card'][data-part='content'] {
     /* 尺寸档只换这两个私有槽。size 落在 content 上而非 root：root 是可选部件，
        面板几何也长在 content 上。语气不接：卡片是内容容器，语气该由里面的内容表达 */
-    --xh-_hover-card-py: var(--xh-space-3);
-    --xh-_hover-card-px: var(--xh-control-px-md);
+    --xh-_hover-card-pad: var(--xh-surface-pad-md);
     --xh-_hover-card-max-w: var(--xh-overlay-max-w);
 
     position: relative;
@@ -96,18 +105,32 @@
     flex-direction: column;
     gap: var(--xh-hover-card-gap, var(--xh-space-2));
     inline-size: max-content;
-    max-inline-size: var(--xh-hover-card-max-w, var(--xh-_hover-card-max-w));
+    /* 静态档与落位后的可用宽度取小：窄视口下面板伸出去，最右侧的内容就点不到了 */
+    max-inline-size: min(var(--xh-hover-card-max-w, var(--xh-_hover-card-max-w)), var(--xh-_hover-card-available-w));
     /* 内容由作者给，长度不可预知：不限高就整块伸出视口且滚不到 */
     max-block-size: min(var(--xh-hover-card-max-h, var(--xh-overlay-max-h)), var(--xh-_hover-card-available-h));
     overflow-y: auto;
-    padding-block: var(--xh-hover-card-py, var(--xh-_hover-card-py));
-    padding-inline: var(--xh-hover-card-px, var(--xh-_hover-card-px));
-    border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-border-default));
-    border-radius: var(--xh-hover-card-radius, var(--xh-shape-surface));
-    background: var(--xh-hover-card-bg, var(--xh-bg-surface));
-    color: var(--xh-hover-card-fg, var(--xh-fg-default));
-    box-shadow: var(--xh-hover-card-shadow, var(--xh-elevation-floating));
+    /* 浮在页面之上的 Overlay 滚动面（§6.6）：滚到头不把页面一起带走 */
+    overscroll-behavior: contain;
+    padding-block: var(--xh-hover-card-py, var(--xh-_hover-card-pad));
+    padding-inline: var(--xh-hover-card-px, var(--xh-_hover-card-pad));
+    border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-material-frosted-border));
+    border-radius: var(--xh-hover-card-radius, var(--xh-shape-overlay));
+    /* 与气泡族共用 M2：顶光只占一像素，正文保持实体，只在内容层采样一次背景。 */
+    background:
+      linear-gradient(
+        to bottom,
+        var(--xh-material-frosted-highlight) 0 var(--xh-stroke-thin),
+        transparent var(--xh-stroke-thin)
+      ),
+      var(--xh-hover-card-bg, var(--xh-material-frosted-bg));
+    color: var(--xh-hover-card-fg, var(--xh-material-frosted-fg));
+    box-shadow: var(--xh-hover-card-shadow, var(--xh-material-frosted-shadow));
+    -webkit-backdrop-filter: var(--xh-hover-card-backdrop, var(--xh-material-frosted-backdrop));
+    backdrop-filter: var(--xh-hover-card-backdrop, var(--xh-material-frosted-backdrop));
     pointer-events: auto;
+    /* 进退场的缩放锚在贴着锚点的那条边上；两个分量由 positioner 按 placement 写进私有槽 */
+    transform-origin: var(--xh-_overlay-origin-x, 50%) var(--xh-_overlay-origin-y, 50%);
   }
 
   /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
@@ -122,7 +145,9 @@
   }
 
   [data-scope='hover-card'][data-part='content'][data-state='open'] {
-    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    animation: xh-overlay-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+    /* 只在开着的这一档挂：合成层随 data-state 一起收走，收起后不再占着 */
+    will-change: opacity, scale, translate;
   }
 
   /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
@@ -132,20 +157,31 @@
   }
 
   /* —— 尺寸 —— */
-  /* 缺省档写在 content 的基础规则里；行内内缩本就取 control-px 那把尺，上下各挪一档，
-     纵向内缩按 space 档同步 */
+  /* 缺省档写在 content 的基础规则里；四边等宽的面板内衬三档取 surface-pad 那把尺 */
   [data-scope='hover-card'][data-part='content'][data-size='sm'] {
-    --xh-_hover-card-py: var(--xh-space-2);
-    --xh-_hover-card-px: var(--xh-control-px-sm);
+    --xh-_hover-card-pad: var(--xh-surface-pad-sm);
     --xh-_hover-card-max-w: var(--xh-overlay-max-w-sm);
   }
 
   [data-scope='hover-card'][data-part='content'][data-size='lg'] {
-    --xh-_hover-card-py: var(--xh-space-4);
-    --xh-_hover-card-px: var(--xh-control-px-lg);
+    --xh-_hover-card-pad: var(--xh-surface-pad-lg);
     --xh-_hover-card-max-w: var(--xh-overlay-max-w-lg);
   }
 
+  [data-scope='hover-card'][data-part='title'] {
+    margin: 0;
+    font-size: var(--xh-hover-card-title-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-hover-card-title-font-weight, var(--xh-font-weight-semibold));
+    color: var(--xh-hover-card-title-fg, var(--xh-fg-default));
+  }
+
+  /* 说明文字走说明档（§6.4）：13px + fg-muted */
+  [data-scope='hover-card'][data-part='description'] {
+    margin: 0;
+    font-size: var(--xh-hover-card-description-font-size, var(--xh-text-secondary-size));
+    color: var(--xh-hover-card-description-fg, var(--xh-fg-muted));
+  }
+
   /* 箭头的底色与描边色，几何在 overlay-arrow.css。
      交叉轴落点由定位引擎经内联自定义属性写进来，没给时退回居中 */
   [data-scope='hover-card'][data-part='arrow'] {
@@ -155,7 +191,21 @@
     --xh-_overlay-arrow-x: var(--xh-_hover-card-arrow-x);
     --xh-_overlay-arrow-y: var(--xh-_hover-card-arrow-y);
 
-    background: var(--xh-hover-card-bg, var(--xh-bg-surface));
-    border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-border-default));
+    background: var(--xh-hover-card-bg, var(--xh-material-frosted-bg));
+    border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-material-frosted-border));
+  }
+
+  @media (forced-colors: active) {
+    [data-scope='hover-card'][data-part='content'] {
+      background-image: none;
+    }
+  }
+
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    [data-scope='hover-card'][data-part='positioner'] {
+      display: none;
+    }
   }
 }

package/css/icon-wrapper.css

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 icon wrapper 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='icon-wrapper'] {
@@ -10,7 +17,8 @@
     /* 私有槽位：底座直径与图元直径，换档只改这两个 */
     --xh-_icon-wrapper-size: var(--xh-icon-wrapper-size, var(--xh-control-h-md));
 
-    /* 流给里面的图元；图元自己写了档位时仍按自己的档走 */
+    /* 流给里面的图元——包括自己写了档位的那一枚，它的档位取值也读这个槽，
+       图元直径因此始终跟着底座换档 */
     --xh-icon-size: var(--xh-icon-wrapper-glyph-size, var(--xh-glyph-size-md));
 
     display: inline-flex;
@@ -20,7 +28,7 @@
     inline-size: var(--xh-_icon-wrapper-size);
     block-size: var(--xh-_icon-wrapper-size);
     border: var(--xh-stroke-thin) solid transparent;
-    border-radius: var(--xh-icon-wrapper-radius, var(--xh-shape-pill));
+    border-radius: var(--xh-icon-wrapper-radius, var(--xh-shape-circle));
     background: var(--xh-icon-wrapper-bg, var(--xh-bg-subtle));
     color: var(--xh-icon-wrapper-fg, var(--xh-fg-default));
     line-height: var(--xh-leading-none);
@@ -33,10 +41,14 @@
   }
 
   /* —— 形态 —— */
-  /* 形态只决定颜色怎么用；用哪族颜色由 data-tone 决定，没写 tone 就沿用原来的品牌/中性配色 */
+  /* 形态只决定颜色怎么用；用哪族颜色由 data-tone 决定，没写 tone 就沿用原来的品牌/中性配色。
+     实心档还在顶边画一条极浅的内高光，把这块底座衬出厚度；另外三档面上没有实心底，不画 */
   [data-scope='icon-wrapper'][data-part='root'][data-variant='solid'] {
+    --xh-_icon-wrapper-highlight: var(--xh-_highlight-tone);
+
     background: var(--xh-_tone, var(--xh-bg-brand));
     color: var(--xh-_tone-on, var(--xh-fg-on-brand));
+    box-shadow: var(--xh-icon-wrapper-shadow, var(--xh-_icon-wrapper-highlight));
   }
 
   [data-scope='icon-wrapper'][data-part='root'][data-variant='subtle'] {

package/css/icon.css

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 icon 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='icon'] {
@@ -30,24 +37,56 @@
     display: none;
   }
 
-  /* 三档直径，缺省档写在上面的基础规则里 */
+  /* 八档直径，缺省档 md 写在上面的基础规则里。
+     每一档都把 --xh-icon-size 排在自己的档值前面：这个槽是外层统一图元直径的通道，
+     档值直接写终值的话，写了 data-size 的那一枚就脱离外层控制，作者在祖先上的覆盖也改不动它 */
+  [data-scope='icon'][data-part='root'][data-size='text'] {
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+  }
+
   [data-scope='icon'][data-part='root'][data-size='sm'] {
-    inline-size: var(--xh-glyph-size-sm);
-    block-size: var(--xh-glyph-size-sm);
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-sm));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-sm));
+  }
+
+  [data-scope='icon'][data-part='root'][data-size='md'] {
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-md));
   }
 
   [data-scope='icon'][data-part='root'][data-size='lg'] {
-    inline-size: var(--xh-glyph-size-lg);
-    block-size: var(--xh-glyph-size-lg);
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-lg));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-lg));
+  }
+
+  [data-scope='icon'][data-part='root'][data-size='xl'] {
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-xl));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-xl));
+  }
+
+  [data-scope='icon'][data-part='root'][data-size='2xl'] {
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-2xl));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-2xl));
+  }
+
+  [data-scope='icon'][data-part='root'][data-size='3xl'] {
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-3xl));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-3xl));
   }
 
-  /* 三档描边，缺省档同样写在基础规则里 */
+  [data-scope='icon'][data-part='root'][data-size='4xl'] {
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-4xl));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-4xl));
+  }
+
+  /* 三档描边，缺省档同样写在基础规则里；--xh-icon-stroke 同样排在档值前面 */
   [data-scope='icon'][data-part='root'][data-weight='light'] {
-    stroke-width: var(--xh-glyph-stroke-light);
+    stroke-width: var(--xh-icon-stroke, var(--xh-glyph-stroke-light));
   }
 
   [data-scope='icon'][data-part='root'][data-weight='bold'] {
-    stroke-width: var(--xh-glyph-stroke-bold);
+    stroke-width: var(--xh-icon-stroke, var(--xh-glyph-stroke-bold));
   }
 
   /* 语气：图标没有底色，语气只落在前景上，取普通背景上表达该语气的那档文字色。
@@ -56,4 +95,31 @@
   [data-scope='icon'][data-part='root'][data-tone] {
     color: var(--xh-icon-fg, var(--xh-_tone-fg, currentColor));
   }
+
+  /* 旋转：四分之一圈的整数倍，是把箭头指向别处的结构性角度，不是可调幅度。
+     没有过渡也没有动画——转到位就停在那儿，减弱动效那一档碰不到它 */
+  [data-scope='icon'][data-part='root'][data-rotate='90'] {
+    rotate: 90deg;
+  }
+
+  [data-scope='icon'][data-part='root'][data-rotate='180'] {
+    rotate: 180deg;
+  }
+
+  [data-scope='icon'][data-part='root'][data-rotate='270'] {
+    rotate: 270deg;
+  }
+
+  /* 翻转：沿轴取反，同样是静态几何。与旋转是两个独立属性，同写时自然叠加 */
+  [data-scope='icon'][data-part='root'][data-flip='horizontal'] {
+    scale: -1 1;
+  }
+
+  [data-scope='icon'][data-part='root'][data-flip='vertical'] {
+    scale: 1 -1;
+  }
+
+  [data-scope='icon'][data-part='root'][data-flip='both'] {
+    scale: -1 -1;
+  }
 }