@xihan-ui/styles 2.0.0 → 3.0.0

package/family/collection-item.css

@@ -53,10 +53,12 @@
        描边在这里常驻 solid、静息透明，靠颜色表达键盘高亮。宿主页面常见的
        button:focus:not(:focus-visible) { outline: none } 复位（VitePress 等）是无层规则，压过本份；
        指针落焦时它把简写复位成 none，outline-color 同时落到 currentColor；焦点离开、规则失效的那一刻
-       solid 立即回来，颜色若还在过渡就画成一圈实心边（上一条目闪边）。颜色即时切换后这条路径没有中间帧 */
+       solid 立即回来，颜色若还在过渡就画成一圈实心边（上一条目闪边）。颜色即时切换后这条路径没有中间帧。
+       不透明度同一节奏：集合在后台刷新时保留上一帧、条目按 micro 淡下，数据到了再淡回 */
     transition:
-      background-color var(--xh-motion-duration-release) var(--xh-motion-ease-release),
-      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+      background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   [data-xh-collection-item][data-xh-collection-size='sm'] {
@@ -103,18 +105,25 @@
     font-size: var(--xh-collection-description-font-size, var(--xh-control-caption-md));
   }
 
+  /* 快捷键提示：与说明同档同色的次级文字，只是落位在行尾而不是第 2 行。
+     不换行——它是一串按键记号，折行会被读成两个组合。跟着 description 那支前景走，因此也不跟语气。 */
   [data-xh-collection-slot='shortcut'] {
     grid-column: shortcut;
+    color: var(--xh-_collection-description-fg);
+    font-size: var(--xh-collection-shortcut-font-size, var(--xh-control-caption-md));
+    white-space: nowrap;
   }
 
   [data-xh-collection-slot='suffix'] {
     grid-column: suffix;
   }
 
+  /* 对号常驻在 indicator 列、未选中时透明：按选中态淡变，不按 visibility 瞬切 */
   [data-xh-collection-slot='indicator'] {
     grid-column: indicator;
     color: var(--xh-_collection-indicator-fg);
-    visibility: hidden;
+    opacity: 0;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   [data-xh-collection-slot='shortcut'],
@@ -124,20 +133,9 @@
     margin-inline-start: var(--xh-collection-gap, var(--xh-_collection-gap));
   }
 
-  /* page 上下文：对号是前导标记（leading）；当前项的起始侧指示条按配方开关（none），none 即只由行面与字色表达。 */
+  /* page 上下文：对号与 overlay 同在行尾的 indicator 列（trailing）；当前项的起始侧指示条按配方开关（none），none 即只由行面与字色表达。 */
   [data-xh-collection-item][data-xh-collection-context='page'] {
     position: relative;
-    grid-template-columns:
-      [indicator] max-content
-      [prefix] max-content
-      [text] minmax(0, 1fr)
-      [shortcut] max-content
-      [suffix] max-content;
-  }
-
-  [data-xh-collection-item][data-xh-collection-context='page'] [data-xh-collection-slot='indicator'] {
-    margin-inline-start: 0;
-    margin-inline-end: var(--xh-collection-gap, var(--xh-_collection-gap));
   }
 
   [data-xh-collection-item][data-in-path] {
@@ -188,6 +186,31 @@
     transition-timing-function: var(--xh-motion-ease-press);
   }
 
+  /* 语气段：条目自身动作的性质，静息只换字、hover / 高亮 / 按下换语气淡底，节奏与中性行一致。
+     必须排在上下文段之前：语气与 selected / current 同特指度，靠源序让选中与当前压过语气。 */
+  [data-xh-collection-item][data-tone]:not([data-xh-collection-context='nav']):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) {
+    --xh-_collection-bg: transparent;
+    --xh-_collection-fg: var(--xh-tone-fg);
+  }
+
+  [data-xh-collection-item][data-tone]:not([data-xh-collection-context='nav']):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):hover {
+    --xh-_collection-bg: var(--xh-tone-subtle);
+    --xh-_collection-fg: var(--xh-tone-fg);
+  }
+
+  [data-xh-collection-item][data-tone]:not([data-xh-collection-context='nav']):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:focus-visible, [data-highlighted]) {
+    --xh-_collection-bg: var(--xh-tone-subtle);
+    --xh-_collection-fg: var(--xh-tone-fg);
+  }
+
+  [data-xh-collection-item][data-tone]:not([data-xh-collection-context='nav']):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:active, [data-pressed]) {
+    --xh-_collection-bg: var(--xh-tone-subtle-hover);
+    --xh-_collection-fg: var(--xh-tone-fg);
+
+    transition-duration: var(--xh-motion-duration-press);
+    transition-timing-function: var(--xh-motion-ease-press);
+  }
+
   [data-xh-collection-item][data-xh-collection-context='overlay']:is([aria-selected='true'], [data-selected]):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) {
     --xh-_collection-bg: var(--xh-collection-bg-selected, transparent);
     --xh-_collection-fg: var(--xh-collection-fg-selected, var(--xh-material-frosted-fg));
@@ -436,7 +459,7 @@
   }
 
   [data-xh-collection-item]:is([aria-selected='true'], [data-state='checked']) [data-xh-collection-slot='indicator'] {
-    visibility: visible;
+    opacity: 1;
   }
 
   [data-xh-collection-item][data-state='checked'] {
@@ -489,16 +512,6 @@
     display: none;
   }
 
-  :where([data-motion='reduce']) [data-xh-collection-item] {
-    transition: none;
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    [data-xh-collection-item] {
-      transition: none;
-    }
-  }
-
   @media (forced-colors: active) {
     [data-xh-collection-item] {
       --xh-_collection-bg: Canvas;
@@ -535,6 +548,36 @@
       --xh-_collection-indicator-fg: HighlightText;
     }
 
+    /* 语气在强制颜色下退出：逐态用系统色盖回家族缺省，只留图标与文案通道。
+       语气段在媒体查询外的特指度比这里的基础态各高一级，必须逐条同形盖回，不能只写一条。 */
+    [data-xh-collection-item][data-tone]:not([data-xh-collection-context='nav']):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) {
+      --xh-_collection-bg: Canvas;
+      --xh-_collection-fg: CanvasText;
+      --xh-_collection-outline: transparent;
+      --xh-_collection-indicator-fg: ButtonText;
+    }
+
+    [data-xh-collection-item][data-tone]:not([data-xh-collection-context='nav']):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):hover {
+      --xh-_collection-bg: Highlight;
+      --xh-_collection-fg: HighlightText;
+      --xh-_collection-outline: transparent;
+      --xh-_collection-indicator-fg: HighlightText;
+    }
+
+    [data-xh-collection-item][data-tone]:not([data-xh-collection-context='nav']):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:focus-visible, [data-highlighted]) {
+      --xh-_collection-bg: Canvas;
+      --xh-_collection-fg: CanvasText;
+      --xh-_collection-outline: Highlight;
+      --xh-_collection-indicator-fg: Highlight;
+    }
+
+    [data-xh-collection-item][data-tone]:not([data-xh-collection-context='nav']):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:active, [data-pressed]) {
+      --xh-_collection-bg: Highlight;
+      --xh-_collection-fg: HighlightText;
+      --xh-_collection-outline: transparent;
+      --xh-_collection-indicator-fg: HighlightText;
+    }
+
     [data-xh-collection-item][data-xh-collection-context='overlay']:is([aria-selected='true'], [data-selected]):not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]) {
       --xh-_collection-bg: Canvas;
       --xh-_collection-fg: CanvasText;

package/family/field-chrome.css

@@ -38,8 +38,7 @@
     transition:
       background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
       border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
-      box-shadow var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
-      outline-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+      box-shadow var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   [data-xh-field-chrome][data-variant='outline'] {
@@ -236,16 +235,6 @@
     -webkit-text-fill-color: var(--xh-field-autofill-fg, var(--xh-fg-default));
   }
 
-  @media (prefers-reduced-motion: reduce) {
-    [data-xh-field-chrome] {
-      transition: none;
-    }
-  }
-
-  :where([data-motion='reduce']) [data-xh-field-chrome] {
-    transition: none;
-  }
-
   @media (forced-colors: active) {
     [data-xh-field-chrome] {
       background-color: Canvas;

package/family/loading-ring.css

@@ -0,0 +1,95 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/*
+ * 加载环家族配方：「这里正在等」的那枚圆环，与 Spinner 环档同一副画法——一整圈轨道色，
+ * 只有起始边换成前景色，绕中心匀速转，转起来才看得出方向。
+ *
+ * 连接层在承载者上投影 data-xh-loading-ring，并用共享的 data-loading 说此刻在不在等。
+ * 环画在承载者的 ::before 上：伪元素有没有、多大、摆在哪由皮肤决定（皮肤写 content 与尺寸），
+ * 配方只负责把它画成环、随 data-loading 淡入淡出并转停。收起时环停在当前角度淡出，
+ * 与皮肤里接替它的那枚字形交叉淡变；不在等时不转。
+ *
+ * 轨道取 --xh-border-default、环粗取 --xh-stroke-thick；起始边颜色走私有槽 --xh-_loading-ring-fg，
+ * 皮肤按自己的语气与公开槽给，没给时取 currentColor。转一圈的时长走私有槽 --xh-_loading-ring-duration，
+ * 皮肤把自己的公开时长槽接进来，没给时取 --xh-motion-loop-spin。
+ *
+ * 进行中的动作钮投影 data-xh-loading-ring="overlay"：环居中压在钮上、不占排布，钮宽不变，直径取钮的图标档。
+ * 进入在途要等一个 micro 才起淡，不到一个 micro 就结束的短请求什么都不闪；退出在途不等，按 micro 淡出。
+ * 钮里原有的内容由皮肤按同一段等待淡出留位，与环交叉。
+ *
+ * 转圈与淡变的关键帧与时长走 motion.css：引入本配方的皮肤同时 @import 它；家族文件之间不互相引入，
+ * 全量入口里每份家族只内联一次。
+ */
+@layer xihan.components {
+  [data-xh-loading-ring]::before {
+    /* 环粗算进直径，换厚度不会把环撑大 */
+    box-sizing: border-box;
+    border: var(--xh-stroke-thick) solid var(--xh-border-default);
+    border-block-start-color: var(--xh-_loading-ring-fg, currentColor);
+    border-radius: var(--xh-shape-circle);
+    /* 承载者的这枚伪元素在别的状态下可能画着字形：环不带底、不带遮罩 */
+    background: none;
+    -webkit-mask: none;
+    mask: none;
+    opacity: 0;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+    /* 不在等时停在当前角度，淡出途中不先跳回零度 */
+    animation: xh-spin var(--xh-_loading-ring-duration, var(--xh-motion-loop-spin)) var(--xh-motion-ease-loop) infinite paused;
+  }
+
+  [data-xh-loading-ring][data-loading]::before {
+    opacity: 1;
+    animation-play-state: running;
+  }
+
+  /* 压在动作钮上的环：钮是定位盒（Action Control 给 position: relative），环在钮正中、不进排布 */
+  [data-xh-loading-ring='overlay']::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+    margin: auto;
+    pointer-events: none;
+  }
+
+  /* 只在进入在途时等：退出那一刻撤掉这一档，淡出不延迟 */
+  [data-xh-loading-ring='overlay'][data-loading]::before {
+    transition-delay: var(--xh-motion-duration-micro);
+  }
+
+  /* 减弱动效与打印：环停下并整圈换成点线，静止的形状仍读得出「还没好」；淡入淡出照常。
+     两组规则是同一件事的两个触发条件：系统偏好与作者打的 data-motion */
+  @media (prefers-reduced-motion: reduce) {
+    [data-xh-loading-ring]::before {
+      border-style: dotted;
+      border-color: var(--xh-_loading-ring-fg, currentColor);
+      animation: none;
+    }
+  }
+
+  :where([data-motion='reduce']) [data-xh-loading-ring]::before {
+    border-style: dotted;
+    border-color: var(--xh-_loading-ring-fg, currentColor);
+    animation: none;
+  }
+
+  @media print {
+    [data-xh-loading-ring]::before {
+      border-style: dotted;
+      border-color: var(--xh-_loading-ring-fg, currentColor);
+      animation: none;
+    }
+  }
+
+  /* 强制色：轨道取系统文字色，起始边取高亮色，转向照样读得出 */
+  @media (forced-colors: active) {
+    [data-xh-loading-ring]::before {
+      border-color: CanvasText;
+      border-block-start-color: Highlight;
+    }
+  }
+}

package/family/material.css

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/*
+ * 材质家族配方：frosted 面，以及它在 liquid 档的替身。
+ *
+ * 连接层在部件上投影 data-xh-material="frosted"：锚定瞬态浮层的内容面（菜单、选择、气泡、浮动面板……）
+ * 与浮在内容之上的圆钮（回到顶部、浮动钮、轮播控制、回到底部）。配方在部件上声明一组私有槽
+ * --xh-_material-*，一种材质一套取值：底、交互阶梯（悬停 / 按下 / 键盘聚焦面）、前景、描边、投影、
+ * 背景滤镜与 1px 内侧顶光。
+ *
+ *   面      配方直接画描边、背景（1px 顶光叠在底色之上，随面本身不随内容滚动）、前景、投影与背景滤镜，
+ *           读桥接槽 --xh-frosted-*；皮肤只把使用者槽接进来：--xh-frosted-bg: var(使用者槽, var(--xh-_material-bg))
+ *   圆钮    面由 Action Control 家族画，皮肤把 --xh-action-* 桥接槽指向这组私有槽；配方只补背景滤镜
+ *
+ * data-material="liquid" 下，同时投影了 data-xh-liquid 的部件把这组私有槽换成液态面的取值（液态层
+ * liquid.css 在同一部件上声明 --xh-_liquid-*），皮肤不必为液态档再写一遍；可按的圆钮挂上按住形变。
+ * 减少透明、高对比、强制色与打印由材质令牌在令牌层降级，这里不另写。
+ */
+@layer xihan.components {
+  [data-xh-material='frosted'] {
+    --xh-_material-bg: var(--xh-material-frosted-bg);
+    /* 圆钮的交互阶梯：磨砂面半透明，悬停 / 按下换成不透明的淡底一档、二档，不叠在透景上发灰 */
+    --xh-_material-bg-hover: var(--xh-_tone-subtle, var(--xh-bg-subtle-opaque));
+    --xh-_material-bg-pressed: var(--xh-_tone-subtle-hover, var(--xh-bg-subtle-hover-opaque));
+    --xh-_material-bg-focus: var(--xh-material-frosted-focus-surface);
+    --xh-_material-fg: var(--xh-material-frosted-fg);
+    --xh-_material-border: var(--xh-material-frosted-border);
+    --xh-_material-shadow: var(--xh-material-frosted-shadow);
+    --xh-_material-backdrop: var(--xh-material-frosted-backdrop);
+    --xh-_material-highlight: var(--xh-material-frosted-highlight);
+
+    -webkit-backdrop-filter: var(--xh-frosted-backdrop, var(--xh-_material-backdrop));
+    backdrop-filter: var(--xh-frosted-backdrop, var(--xh-_material-backdrop));
+  }
+
+  /* 面：四件套加 1px 顶光。顶光是背景的最上一层，只占内侧一像素、画在面本身上，滚动的内容面也钉在顶上；
+     高对比与强制色下令牌把它归零，四边描边照常完整 */
+  [data-xh-material='frosted']:not([data-xh-action-control]) {
+    border: var(--xh-stroke-thin) solid var(--xh-frosted-border, var(--xh-_material-border));
+    background:
+      linear-gradient(
+        to bottom,
+        var(--xh-frosted-highlight, var(--xh-_material-highlight)) 0 var(--xh-stroke-thin),
+        transparent var(--xh-stroke-thin)
+      ),
+      var(--xh-frosted-bg, var(--xh-_material-bg));
+    color: var(--xh-frosted-fg, var(--xh-_material-fg));
+    box-shadow: var(--xh-frosted-shadow, var(--xh-_material-shadow));
+  }
+
+  /* liquid 档：浮在内容之上的导航层部件换成液态面。同一组私有槽换值，皮肤的桥接照旧；面内不加顶光，
+     亮边已由液态层画在朝光源的一侧 */
+  :where([data-material='liquid']) [data-xh-material][data-xh-liquid] {
+    --xh-_material-bg: var(--xh-_liquid-bg);
+    --xh-_material-bg-hover: var(--xh-_liquid-bg-hover);
+    --xh-_material-bg-pressed: var(--xh-_liquid-bg-pressed);
+    --xh-_material-bg-focus: var(--xh-material-liquid-focus-surface);
+    --xh-_material-fg: var(--xh-material-liquid-fg);
+    --xh-_material-border: var(--xh-material-liquid-border);
+    --xh-_material-shadow: var(--xh-_liquid-shadow);
+    --xh-_material-backdrop: var(--xh-material-liquid-backdrop);
+    --xh-_material-highlight: transparent;
+  }
+
+  /* 按住液态圆钮时的黏滞形变由液态面逐帧写进来，松手弹回。只挂在可按的面上 */
+  :where([data-material='liquid']) [data-xh-action-control][data-xh-material][data-xh-liquid] {
+    transform: var(--xh-_liquid-deform);
+  }
+}

package/family/menu-choice.css

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* Menu / ContextMenu / Menubar 的 checkbox 与 radio 共用标记语言。 */
+
+@layer xihan.components {
+  [data-xh-menu-choice-indicator] {
+    visibility: hidden;
+    opacity: 0;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  [data-xh-menu-choice-indicator][data-state='checked'] {
+    visibility: visible;
+    opacity: 1;
+  }
+
+  [data-xh-menu-choice-indicator='checkbox']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-control-indicator-size));
+    block-size: var(--xh-icon-size, var(--xh-control-indicator-size));
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-check) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-check) center / contain no-repeat;
+  }
+
+  [data-xh-menu-choice-indicator='radio']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-space-2);
+    block-size: var(--xh-space-2);
+    border-radius: var(--xh-shape-circle);
+    background-color: currentColor;
+  }
+
+  /* 强制色：勾与圆点都是伪元素上的一块底色，这一档里会被换成 Canvas 而消失；退出强制换色、直接写系统前景。
+     标记坐在菜单条目里，按下与没被高亮时的悬停，家族把条目涂成 Highlight，标记跟着换 HighlightText；禁用取 GrayText */
+  @media (forced-colors: active) {
+    [data-xh-menu-choice-indicator]:empty::before {
+      forced-color-adjust: none;
+      background-color: CanvasText;
+    }
+
+    [data-xh-collection-item]:not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:active, [data-pressed], :hover:not(:focus-visible, [data-highlighted]))
+      [data-xh-menu-choice-indicator]:empty::before {
+      background-color: HighlightText;
+    }
+
+    [data-xh-menu-choice-indicator][data-disabled]:empty::before {
+      background-color: GrayText;
+    }
+  }
+}

package/family/motion.css

@@ -5,7 +5,7 @@
 
 /* 定义 motion 样式。 */
 
-/* 共享关键帧的唯一真源（规范 §9.4 / §9.5）。
+/* 共享关键帧的唯一真源。
  *
  * 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
  * 动画会静默地整个不跑。所以引用这里任一名字的皮肤都 @import 本文件，单独引入那份皮肤时
@@ -13,17 +13,17 @@
  * @import 去重，同名同帧体即使重复插入也无副作用。
  *
  * 本文件只放跨皮肤共用的关键帧，皮肤内不得重定义这些名字（check-keyframe-refs 判红）；
- * 组件专属关键帧仍住在各自皮肤。幅度只引 --xh-motion-distance-sm 与 --xh-motion-scale-enter /
- * -exit，减弱动效档由令牌层把它们归零。四个方向槽 --xh-_overlay-enter-* 由浮层皮肤按
- * placement 写在 positioner 上，四个都没写时位移退回 0。
+ * 组件专属关键帧仍住在各自皮肤。幅度只引 --xh-motion-distance-sm / -md 与 --xh-motion-scale-enter /
+ * -exit，整幅位移经私有槽取 --xh-motion-travel，减弱动效档由令牌层把它们归零。四个方向槽
+ * --xh-_overlay-enter-* 由浮层皮肤按 placement 写在 positioner 上，四个都没写时位移退回 0。
  */
 @layer xihan.motion {
   /* ── 锚定列表 / 菜单：沿落位方向短位移，不缩放文字与选中标记 ──
      Menu、Select、Combobox、Cascader、ContextMenu、Menubar、Mention、TreeSelect、
-     Date / Time picker、Tooltip */
+     Date / Time picker、ColorPicker、Tooltip */
   @keyframes xh-overlay-slide-in {
     from {
-      opacity: 0;
+      opacity: var(--xh-_enter-from-opacity, 0);
       translate:
         calc((var(--xh-_overlay-enter-right, 0) - var(--xh-_overlay-enter-left, 0)) * var(--xh-motion-distance-sm))
         calc((var(--xh-_overlay-enter-down, 0) - var(--xh-_overlay-enter-up, 0)) * var(--xh-motion-distance-sm));
@@ -54,7 +54,7 @@
      起点朝哪个方向退让由 placement 写进四个方向槽（那一侧写 1），四个都没写就退回原地缩放 */
   @keyframes xh-overlay-pop-in {
     from {
-      opacity: 0;
+      opacity: var(--xh-_enter-from-opacity, 0);
       scale: var(--xh-motion-scale-enter);
       translate:
         calc((var(--xh-_overlay-enter-right, 0) - var(--xh-_overlay-enter-left, 0)) * var(--xh-motion-distance-sm))
@@ -82,10 +82,12 @@
   }
 
   /* ── 无锚定弹出：原地缩放淡入，没有方向 ──
-     NavigationMenu、SideNav popout、FloatingPanel、FloatButton 列表、Pagination 弹层 */
+     NavigationMenu、SideNav popout、FloatingPanel、FloatButton 列表、Pagination 弹层；
+     页内浮现的小件也取它：Approval、QuestionFlow 的结果标记，MessageFeed、Log 的回底钮；
+     行内横排的胶囊集合（TagsInput、TagGroup、Select 标签行）加入一枚也取它：竖向上浮与来源方向不符，还会探出字段外壳 */
   @keyframes xh-pop-in {
     from {
-      opacity: 0;
+      opacity: var(--xh-_enter-from-opacity, 0);
       scale: var(--xh-motion-scale-enter);
     }
 
@@ -100,7 +102,7 @@
      Cascader 列项的淡入 */
   @keyframes xh-fade-in {
     from {
-      opacity: 0;
+      opacity: var(--xh-_enter-from-opacity, 0);
     }
 
     to {
@@ -121,7 +123,7 @@
   /* 页内内容的上浮进场：淡入叠一小段向上位移。Command 的分组、EmptyState、QuestionFlow */
   @keyframes xh-rise-in {
     from {
-      opacity: 0;
+      opacity: var(--xh-_enter-from-opacity, 0);
       translate: 0 var(--xh-motion-distance-sm);
     }
 
@@ -163,4 +165,199 @@
       padding-block-end: 0;
     }
   }
+
+  /* ── 列表条目进场：淡入叠一段向上位移，比页内上浮大一档 ──
+     Approval、MessageFeed、QuestionFlow、ToolCall 的条目 */
+  @keyframes xh-item-in {
+    from {
+      opacity: var(--xh-_enter-from-opacity, 0);
+      translate: 0 var(--xh-motion-distance-md);
+    }
+
+    to {
+      opacity: 1;
+      translate: 0 0;
+    }
+  }
+
+  /* 自上而下的显现：新揭开的内容从上方落位。DiffView 展开的折叠块、Form 的错误汇总 */
+  @keyframes xh-drop-in {
+    from {
+      opacity: var(--xh-_enter-from-opacity, 0);
+      translate: 0 calc(-1 * var(--xh-motion-distance-sm));
+    }
+
+    to {
+      opacity: 1;
+      translate: 0 0;
+    }
+  }
+
+  /* ── 面板（sheet）：模态与强反馈面，竖向一小段位移叠缩放 ──
+     位移与缩放写独立属性，互不覆盖，手势期间写 translate 也不会把 scale 抹掉。Dialog、Notification */
+  @keyframes xh-sheet-in {
+    from {
+      opacity: var(--xh-_enter-from-opacity, 0);
+      translate: 0 var(--xh-motion-distance-md);
+      scale: var(--xh-motion-scale-enter);
+    }
+
+    to {
+      opacity: 1;
+      translate: 0 0;
+      scale: 1;
+    }
+  }
+
+  @keyframes xh-sheet-out {
+    from {
+      opacity: 1;
+      translate: 0 0;
+      scale: 1;
+    }
+
+    to {
+      opacity: 0;
+      translate: 0 var(--xh-motion-distance-md);
+      scale: var(--xh-motion-scale-exit);
+    }
+  }
+
+  /* ── 整幅滑入（slide）：面板从所在边整条推入推出 ──
+     方向由皮肤在元素上写进 --xh-_slide-from-x / --xh-_slide-from-y（取正负整幅位移令牌或 0），
+     两个都没写时位移退回 0。整幅位移令牌在减弱动效下归零，进出场只剩时长。Drawer */
+  @keyframes xh-slide-in {
+    from {
+      translate: var(--xh-_slide-from-x, 0) var(--xh-_slide-from-y, 0);
+    }
+
+    to {
+      translate: 0 0;
+    }
+  }
+
+  @keyframes xh-slide-out {
+    from {
+      translate: 0 0;
+    }
+
+    to {
+      translate: var(--xh-_slide-from-x, 0) var(--xh-_slide-from-y, 0);
+    }
+  }
+
+  /* 整幅滑入配套的淡变：起止端取 --xh-motion-travel-opacity，缺省为 1 即不淡变，
+     减弱动效下为 0，整幅位移归零后由它接住进出场。与 xh-slide-in / -out 并列播放，
+     时长取淡变档（enter / exit），不随几何时长一起归零。Drawer */
+  @keyframes xh-slide-fade-in {
+    from {
+      opacity: var(--xh-_enter-from-opacity, var(--xh-motion-travel-opacity));
+    }
+
+    to {
+      opacity: 1;
+    }
+  }
+
+  @keyframes xh-slide-fade-out {
+    from {
+      opacity: 1;
+    }
+
+    to {
+      opacity: var(--xh-motion-travel-opacity);
+    }
+  }
+
+  /* ── 循环：匀速转圈与扫过的流光 ──
+     时长取循环令牌，减弱动效下由各皮肤停掉并换成静态替代。
+     转圈写独立的 rotate 属性，与元素自身的 transform 叠加而不互相覆盖。
+     流光的亮带从右扫到左：消费方把渐变画成自身两倍宽（background-size: 200% 100%），
+     只移动背景位置，不动布局也不动 transform。Reasoning、ToolCall 的在跑文字 */
+  @keyframes xh-spin {
+    to {
+      rotate: 1turn;
+    }
+  }
+
+  @keyframes xh-shimmer {
+    from {
+      background-position: 150% center;
+    }
+
+    to {
+      background-position: -50% center;
+    }
+  }
+
+  /* 呼吸：进行中、给不出进度、需要被察觉的状态点。明暗与缩放一起起伏，峰值落在 42%，
+     周期 --xh-motion-loop-breathe、缓动 --xh-motion-ease-breathe。只动 opacity 与 scale。
+     光环画在状态点的 ::after 上，同周期从点本身的大小外扩淡尽，只播 3 个周期，状态点本身持续到状态结束。
+     减弱动效下两者都停，状态点停在满不透明度。Badge 的 pulse */
+  @keyframes xh-breathe {
+    0%,
+    100% {
+      opacity: 0.5;
+      scale: var(--xh-motion-scale-breathe);
+    }
+
+    42% {
+      opacity: 1;
+      scale: 1;
+    }
+  }
+
+  @keyframes xh-breathe-halo {
+    from {
+      opacity: 0.32;
+      scale: 1;
+    }
+
+    60%,
+    to {
+      opacity: 0;
+      scale: var(--xh-motion-scale-halo);
+    }
+  }
+
+  /* ── 交互光：一道光沿 1px 描边环扫过一次 ──
+     光带画在三倍宽的背景里、居中，遮罩只留描边环；背景位置从 100% 走到 0%，光带从起始缘外扫到末缘外。
+     只动背景位置，不动几何；只播一遍，不循环 */
+  @keyframes xh-glint {
+    from {
+      background-position: 100% 0;
+    }
+
+    to {
+      background-position: 0% 0;
+    }
+  }
+
+  /* ── 数值：倒计时条从占满一整条收到零 ──
+     条子自己不改尺寸，靠裁切从行尾往行首收：只重绘、不重排。裁掉哪一侧随书写方向由
+     --xh-_countdown-cut-left / -right 给出，缺省按 LTR 收掉右侧；前端的圆角取
+     --xh-_countdown-radius。走一遍就到头，时长由连接层写进 Notification 的时长槽。 */
+  @keyframes xh-countdown {
+    from {
+      clip-path: inset(0 0 0 0 round var(--xh-_countdown-radius, 0));
+    }
+
+    to {
+      clip-path: inset(0 var(--xh-_countdown-cut-right, 100%) 0 var(--xh-_countdown-cut-left, 0) round var(--xh-_countdown-radius, 0));
+    }
+  }
+
+  /* ── 数据：新出现的折线从头描到尾 ──
+     连接层给路径写 pathLength="1" 把长度归一，消费方把虚线设成一整段（stroke-dasharray: 1），
+     虚线偏移从 1 走到 0。只动 stroke-dashoffset，不动几何。时长取 reveal、曲线取 continuous，
+     与柱从基线长出同一档；减弱动效下时长降到 1ms，折线直接在场。CartesianChart */
+  @keyframes xh-draw {
+    from {
+      stroke-dashoffset: 1;
+    }
+
+    to {
+      stroke-dashoffset: 0;
+    }
+  }
 }