@endfield-ui/react 0.3.0 → 1.0.0

package/src/components/README.md

@@ -10,6 +10,7 @@
 | `chip/` | `FilterChip`、`ResourceChip` | [数据展示](../../../../docs/design/components/data-display.md) |
 | `countdown/` | `Countdown` | [数据展示](../../../../docs/design/components/data-display.md) |
 | `stat/` | `Stat` | [数据展示](../../../../docs/design/components/data-display.md) |
+| `rolling-number/` | `RollingNumber`（从 0 滚到终值的数字，放进 `Stat` 的 `value`） | [数据展示](../../../../docs/design/components/data-display.md#滚动数字) |
 | `sparkline/` | `Sparkline` | [数据展示](../../../../docs/design/components/data-display.md) |
 | `data-row/` | `DataRowList`、`DataRow` | [数据展示](../../../../docs/design/components/data-display.md) |
 | `avatar/` | `Avatar`、`AvatarSwitcher`、`AvatarSwitcherItem`（头像切换：一列头像里选一个） | [数据展示](../../../../docs/design/components/data-display.md)、[导航](../../../../docs/design/components/navigation.md) |
@@ -122,6 +123,14 @@ components/
 - 随主题翻转的颜色一律用语义令牌（`surface`、`ink`、`action`…）。只有"有意不随主题变"的填充才直接用 `neutral-*`，并在旁边写一句注释说明原因。
 - 压在反转块（`surface-inverse`）上的强调记号用 `accent-ink-inverse`，压在页面表面上的用 `accent-ink`，都不直接用 `action`：它在浅色底上看不见。
 - 悬停底用 `hover:bg-ink/5`，不用 `surface-sunken`——后者在暗色主题下是纯黑。
+- **只靠底色或阴影说"选中 / 当前"的地方，要另写一份高对比模式（`forced-colors:`）下的画法。** 系统会把作者写的底色都换成页面色、阴影不画：填充反转的块改成 `forced-colors:bg-[Highlight]` 加 `forced-colors:text-[HighlightText]`，底色画的记号改成 `forced-colors:bg-[Highlight]`。系统色关键字只写在 `forced-colors:` 变体里，是"只用令牌"的例外。字压在 `Highlight` 上的那个元素还要加 `forced-colors:forced-color-adjust-none`（不然浏览器会在字后面垫一块页面色），并把它的边线、焦点环一起写成系统色。对应关系和理由见 [色彩](../../../../docs/design/foundations/color.md#高对比模式)。
+- **全靠底色成形的部件，高对比模式下同样要另写**——不只是"选中"。整个是底色画的（滑块、进度条、加载指示、骨架）会直接不见；靠底色围出来的一块（框里的值块、步进器的格子、排期的条目）只剩里面的字。轨道和填上的那一段写成"空心对实心"（轨道 `forced-colors:outline forced-colors:-outline-offset-1`，填充 `forced-colors:bg-[Highlight]`），不靠两种系统色分；围出来的一块补一圈线（`forced-colors:border`）。控件自己的部件用 `ButtonText`，页面上的用 `CanvasText`。还有几件容易漏的：**禁用的字色**写在 `<label>`、`<span>`、`<output>` 上时系统会当普通字换掉，要写明 `GrayText`——禁用的 `<input>` 也要在它自己身上写（`forced-colors:disabled:text-[GrayText]`，[`controlElement`](input/control-box.ts) 里有），浏览器只认写了 `type` 的；**SVG 里写的颜色**（`fill-*`、`stroke-*`）系统不换，要自己写成系统色，直接写在图标 `<svg>` 上的 `text-*` 也一样（图标跟着走的只是继承来的字色）；**占位用的透明边线**（只读的输入框）会被系统显形，写成 `forced-colors:border-[Canvas]`；**说着事的线别用 [`decor`](../lib/decor.ts)**，它在高对比模式下整个去掉（排期里"今天"的竖线）。
+- **按钮这一类在高对比模式下的写法**（按钮、图标按钮、工具栏、分页条是照这几条改的）：
+  - 外形是一圈线，不做成实心块——实心留给"选中"。线只在 `forced-colors:` 下补，平时的尺寸不动：自己要聚焦的元素用 `forced-colors:border`（`outline` 让焦点环占着），不聚焦的容器（带子、条）用 `forced-colors:outline forced-colors:-outline-offset-1` 画在内边距里。用了 `border` 的，伪元素往外补的点击区要跟着多补 1px（它是从线的里沿起算的）。
+  - 平时就是透明、靠外面一层围着的（工具栏里的钮），补外面那一层，不逐个补。
+  - **带状态的类盖得住单写的 `forced-colors:`**：`hover:`、`group-hover:`、`data-disabled:` 都多一层选择器，优先级更高或一样高。颜色会随状态换的地方，高对比模式下那几档各写一份（`forced-colors:group-hover:bg-[ButtonText]`、`forced-colors:data-disabled:text-[GrayText]`）；能在组件里按属性分支的（`disabled ? … : …`），就只放其中一份，不靠优先级。
+  - **不是真的 `disabled` 的禁用**（去掉了地址的链接、工具栏里还走得到的钮）系统不会替它把字换灰，`GrayText` 要自己写。
+  - 放在控件里的 [`Spinner`](spinner/Spinner.tsx) 自己写的是页面的字色：要它和控件上的字一个颜色，用 `className` 换成 `forced-colors:bg-[ButtonText]`。
 - 组件 API 用语义命名（`variant="action"`、`tone="danger"`），不把颜色名写进属性（不要 `yellow`）。
 - **能当链接用的控件，`href` 之外同时收 `render`**（路由库的链接组件）。链接形态里的那个 `<a>` 换成 [`LinkElement`](link-element/LinkElement.tsx)，判断写成 `href !== undefined || render !== undefined`；转给 Base UI 部件的（菜单项）用 [`defined()`](../lib/defined.ts) 去掉没有值的属性，免得把那个元素自己的地址盖掉。
 - 变体写成 `Record<Variant, string>`，用 [`cn()`](../lib/cn.ts) 合并，使用方传入的 `className` 排在最后、可以覆盖内置类。
@@ -135,7 +144,7 @@ components/
 - 用 `group` / `peer` 时给 `group` 起名字（`group/card` + `group-hover/card:`）：不起名的 `group-hover:` 会被外层任何一个 `group` 的悬停带着走，控件一旦被放进别的可悬停容器就会出错。
 - `z-index` 不在组件里写数值，用 [theme.css](../styles/theme.css) 里的层叠变量（`z-(--z-nav)`、`z-(--z-overlay)`、`z-(--z-toast)`、`z-(--z-loader)`）。只在自己内部排先后的（表格冻结的那一列）先用 `isolate` 围起来，再写小的数值。
 - **会粘住不动的格子必须是不透明的**（表格冻结的首列）：滚过去的内容会从半透明的底下面透出来。它的悬停底不能用 `bg-ink/5`，用 `color-mix()` 把同样的比例混进它所在的底色里，得到一个看上去一样的实色。
-- **压在反转块上的焦点环用 `accent-ink-inverse`**（表格的标题带）；压在行动色上的用 `on-action`（全屏菜单的当前项）。普通的焦点色在亮色下是墨色、暗色下是黄色，正好和这两种底撞色。
+- **压在反转块上的焦点环用 `accent-ink-inverse`**（表格的标题带、月历的选中格）；压在行动色上的用 `on-action`（全屏菜单的当前项、楔形页签的选中项、深色面板里的当前项）。普通的焦点色在亮色下是墨色、暗色下是黄色，正好和这两种底撞色。只有环画在块**里面**时才撞：画在外面的（分段选择、工具栏按下的开关钮）隔着 2px 压在页面上，不用换。换了颜色还要看它贴着的那条边外面是什么：`on-action` 是墨色，贴边的话在暗色页面、深色面板上和周围分不开，所以压在行动色上的环都再往里收 2px（`focus-visible:-outline-offset-4`），让环的两边都是黄。
 
 ### 母题与装饰
 
@@ -155,7 +164,7 @@ components/
 - **一块固定深色的区域里还要放别的控件时，把它做成局部主题**（`data-theme="dark"`），里面照常用语义令牌；不要逐个写 `neutral-*`。弹窗的标题带、行带都是这样。
 - **一块跟着主题翻、但总和页面相反的区域（反转块）里要放别的控件时，用 `data-theme="inverse"`**，里面照常用 `bg-surface text-ink`——取到的就是原来的 `surface-inverse` / `ink-inverse`，颜色不变。面板的标题带、表格的表头带、完成横幅都是这样。反转块里不要再嵌反转块。
 - 进出场用基元给的 `data-starting-style` / `data-ending-style` 写 CSS 过渡（`data-starting-style:opacity-0`），不写关键帧。基元等过渡结束才卸载浮层。
-- 没有边线、全靠底色和页面分开的浮层（文字提示）加一圈透明的边线：高对比模式下底色被系统覆盖，边线会自己显形。
+- 没有边线、全靠底色和页面分开的浮层（文字提示）加一圈透明的边线：高对比模式下底色被系统覆盖，边线会自己显形。反过来，只为占位留着的透明边线不想让它显形，就写成 `Canvas`（见上面"全靠底色成形的部件"那一条）。
 - **要画焦点环的元素不要写 `outline-none`。** Tailwind v4 里它把轮廓的线型定成 `none`，后面的 `focus-visible:outline-2` 也跟着画不出来（菜单的选项踩过）。`outline-none` 只留给"焦点环画在别处"的元素：输入框里的 `<input>`、下拉的触发按钮（环在外框上）、弹窗的面。
 - 局部主题里的焦点环如果会画到局部主题之外（外扩 2px），颜色就压在了页面的底色上。轻提示是深色的一块，环是黄的，画到亮色页面上看不见——所以它用画在里面的 `focusRingInset`。
 - 测试里查浮层用角色（`findByRole("dialog")`）。文字提示的内容同时存在于隐藏的描述里，按文字查时要排除 `[hidden]`。

package/src/components/alert/Alert.tsx

@@ -1,4 +1,5 @@
 import type { ComponentProps, ComponentType, ReactNode } from "react";
+import { usePresence } from "../../hooks/usePresence";
 import { Close } from "../../icons/Close";
 import type { IconProps } from "../../icons/createIcon";
 import { StatusDanger } from "../../icons/StatusDanger";
@@ -7,6 +8,7 @@ import { StatusSuccess } from "../../icons/StatusSuccess";
 import { StatusWarning } from "../../icons/StatusWarning";
 import { cn } from "../../lib/cn";
 import { focusRing } from "../../lib/focus-ring";
+import { mergeRefs } from "../../lib/merge-refs";
 
 export type AlertTone = "info" | "success" | "warning" | "danger";
 
@@ -17,8 +19,15 @@ export type AlertProps = Omit<ComponentProps<"div">, "title"> & {
   title?: ReactNode;
   /** 右侧的一个操作，通常是 `text` 按钮 */
   action?: ReactNode;
-  /** 传了就出现关闭图标。提示条自己不隐藏，由使用方决定 */
+  /**
+   * 传了就出现关闭图标。它只负责通知：显示与否由使用方决定——
+   * 要收起的过程，把 `open` 交给提示条；直接不渲染它就是立刻消失
+   */
   onClose?: () => void;
+  /** 置为 `false` 时先收起、淡出，再卸载。默认 `true` */
+  open?: boolean;
+  /** 收完、已经卸载之后触发 */
+  onExited?: () => void;
   /** 关闭图标的可访问名称 */
   closeLabel?: string;
   /** 替换默认图标；传 `null` 去掉 */
@@ -47,18 +56,64 @@ const toneText: Record<AlertTone, string> = {
   danger: "text-danger",
 };
 
+/*
+ * 收起：量一次自己的高度，再把高度、上下的内边距和边线、外边距一起过渡到"它不在了"的样子。
+ * 父容器是纵向排的（flex 的列、grid）时，它一走还少一个行间距：下外边距收到负的行间距，
+ * 卸载的那一刻后面的内容才不会再跳一下。
+ * 不多包一层来做：`className` 是给带边线的这一层的。返回的函数把摆上去的撤掉
+ */
+function collapseOut(node: HTMLElement) {
+  const { style } = node;
+  const before = style.cssText;
+
+  let gap = 0;
+  if (node.parentElement) {
+    const layout = getComputedStyle(node.parentElement);
+    const stacked =
+      layout.display.includes("grid") ||
+      (layout.display.includes("flex") &&
+        layout.flexDirection.startsWith("column"));
+    if (stacked) gap = Number.parseFloat(layout.rowGap) || 0;
+  }
+
+  style.height = `${node.getBoundingClientRect().height}px`;
+  // 先把起点落下去，下面这几样才是"变过去"的
+  node.getBoundingClientRect();
+  style.height = "0px";
+  style.minHeight = "0px";
+  style.paddingBlock = "0px";
+  style.borderBlockWidth = "0px";
+  style.marginTop = "0px";
+  style.marginBottom = `${-gap}px`;
+  style.opacity = "0";
+
+  return () => {
+    style.cssText = before;
+  };
+}
+
 /** 页面内的一条常驻消息。需要用户处理的重要信息用它，不用会消失的轻提示。 */
 export function Alert({
   tone = "info",
   title,
   action,
   onClose,
+  open = true,
+  onExited,
   closeLabel = "关闭",
   icon,
   className,
+  ref,
   children,
   ...props
 }: AlertProps) {
+  const {
+    ref: rootRef,
+    mounted,
+    leaving,
+  } = usePresence<HTMLDivElement>(open, { onLeave: collapseOut, onExited });
+  if (!mounted) return null;
+
   const Icon = toneIcon[tone];
   const graphic = icon === undefined ? <Icon size={20} /> : icon;
 
@@ -66,10 +121,17 @@ export function Alert({
     <div
       role={tone === "danger" || tone === "warning" ? "alert" : "status"}
       {...props}
+      ref={mergeRefs(rootRef, ref)}
       data-tone={tone}
+      // 正在收起的提示条点不到、Tab 不进去
+      inert={leaving}
       className={cn(
         "flex items-start gap-3 border border-l-4 border-line bg-surface-raised py-3 pr-3 pl-3 text-sm text-ink",
         toneBar[tone],
+        leaving && [
+          "pointer-events-none overflow-hidden",
+          "transition-[height,padding,margin,border-width,opacity] duration-(--duration-fast) ease-standard",
+        ],
         className,
       )}
     >

package/src/components/avatar/Avatar.tsx

@@ -31,10 +31,13 @@ const sizeClass: Record<AvatarSize, string> = {
 
 /*
  * 选中环：2px 的间隔 + 3px 的行动色 + 1px 的墨线。
- * 墨线是给亮色页面的——黄色在白底上看不出来
+ * 墨线是给亮色页面的——黄色在白底上看不出来。
+ *
+ * 高对比模式下阴影不画：换成一圈系统"选中"色的边线，画在头像里面
+ * （外面那一圈轮廓留给头像切换的焦点环）
  */
 export const avatarSelectedRing =
-  "shadow-[0_0_0_2px_var(--ef-surface),0_0_0_5px_var(--ef-action),0_0_0_6px_var(--ef-ink)]";
+  "shadow-[0_0_0_2px_var(--ef-surface),0_0_0_5px_var(--ef-action),0_0_0_6px_var(--ef-ink)] forced-colors:border-[3px] forced-colors:border-[Highlight]";
 
 /** 中文名取第一个字；拉丁字母的名字取前两个词的首字母 */
 export function initialsOf(name: string): string {

package/src/components/bracket-title/BracketTitle.tsx

@@ -1,9 +1,13 @@
 import type { ComponentProps, ElementType, ReactNode } from "react";
+import { useInView } from "../../hooks/useInView";
 import { cn } from "../../lib/cn";
+import { mergeRefs } from "../../lib/merge-refs";
 
 export type BracketTitleProps = Omit<ComponentProps<"h3">, "children"> & {
   /** 标题层级，默认 3（`<h3>`） */
   level?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** 进入视口时播放一次入场：括号先到，名称随后。默认开启 */
+  animate?: boolean;
   /** 名称 */
   children: ReactNode;
 };
@@ -16,23 +20,48 @@ const bracket = "font-medium text-ink-tertiary";
  */
 export function BracketTitle({
   level = 3,
+  animate = true,
   className,
   children,
+  ref,
   ...props
 }: BracketTitleProps) {
   const Heading: ElementType = `h${level}`;
+  const [inViewRef, inView] = useInView<HTMLHeadingElement>({
+    disabled: !animate,
+  });
+  // 入场：括号先淡入，名称晚 100ms。只淡入、不位移——它们是排在同一行里的字，行内的字做不了位移
+  const pending = animate && !inView;
+  const playing = animate && inView;
+  const bracketEnter = cn(pending && "opacity-0", playing && "animate-fade-in");
 
   return (
     // 括号和名称排在同一行内而不是弹性盒里：名称换行时，右括号跟在最后一个字后面
     <Heading
       {...props}
+      ref={mergeRefs(inViewRef, ref)}
       className={cn("text-4xl font-bold wrap-anywhere text-ink", className)}
     >
-      <span aria-hidden="true" className={cn(bracket, "mr-[0.4em]")}>
+      <span
+        aria-hidden="true"
+        className={cn(bracket, "mr-[0.4em]", bracketEnter)}
+      >
         [
       </span>
-      {children}
-      <span aria-hidden="true" className={cn(bracket, "ml-[0.4em]")}>
+      <span
+        className={
+          cn(
+            pending && "opacity-0",
+            playing && "animate-fade-in [animation-delay:100ms]",
+          ) || undefined
+        }
+      >
+        {children}
+      </span>
+      <span
+        aria-hidden="true"
+        className={cn(bracket, "ml-[0.4em]", bracketEnter)}
+      >
         ]
       </span>
     </Heading>

package/src/components/button/Button.tsx

@@ -139,6 +139,17 @@ const enabledClass: Record<ButtonVariant, string> = {
   text: "text-ink active:text-ink-secondary",
 };
 
+/*
+ * 高对比模式（forced-colors）下底色被系统换成页面色，带底色的变体只剩一行字：
+ * 补一圈线，竖条、分隔线、加载中的方块这些底色画的记号改用按钮的字色。
+ * 禁用的线、字、记号都是灰字色——链接形态禁用时是一个去掉了地址的 <a>，
+ * 系统不会替它把字换灰，所以字色也写明
+ */
+const forcedOutline = "forced-colors:border";
+const forcedEnabled = "forced-colors:border-[ButtonText]";
+const forcedDisabled =
+  "forced-colors:border-[GrayText] forced-colors:text-[GrayText]";
+
 export function Button(props: ButtonProps) {
   const {
     variant = "control",
@@ -158,6 +169,10 @@ export function Button(props: ButtonProps) {
   const isText = variant === "text";
   const marker = markerColor[variant];
   const iconSize = inlineIconSize[size];
+  // 记号在高对比模式下的颜色：竖条、分隔线、占着记号位的旋转方块共用
+  const forcedMark = disabled
+    ? "forced-colors:bg-[GrayText]"
+    : "forced-colors:bg-[ButtonText]";
 
   const classes = cn(
     "group relative inline-flex shrink-0 items-center justify-center font-medium leading-none whitespace-nowrap select-none",
@@ -173,6 +188,11 @@ export function Button(props: ButtonProps) {
         ? "cursor-not-allowed text-ink-disabled"
         : "cursor-not-allowed bg-disabled text-on-disabled"
       : enabledClass[variant],
+    // text 变体靠下划线成形，不补线；它的下划线跟着字色走，禁用时一起写明
+    !isText && forcedOutline,
+    disabled ? forcedDisabled : !isText && forcedEnabled,
+    // 加载中不是禁用：线和字照旧。链接形态这时候同样去掉了地址，字色写明，和线一个颜色
+    loading && !disabled && "forced-colors:text-[ButtonText]",
     loading && "pointer-events-none",
     block && "flex w-full",
     className,
@@ -187,7 +207,7 @@ export function Button(props: ButtonProps) {
         className="inline-flex items-center justify-center"
         style={{ width: iconSize, height: iconSize }}
       >
-        <Spinner label={null} className="size-2" />
+        <Spinner label={null} className={cn("size-2", forcedMark)} />
       </span>
     ) : (
       <ChevronLeft size={iconSize} />
@@ -199,7 +219,7 @@ export function Button(props: ButtonProps) {
         className="inline-flex items-center justify-center"
         style={{ width: iconSize, height: iconSize }}
       >
-        <Spinner label={null} className="size-2" />
+        <Spinner label={null} className={cn("size-2", forcedMark)} />
       </span>
     ) : (
       <ArrowCorner
@@ -244,7 +264,10 @@ export function Button(props: ButtonProps) {
               markerSpinner[size],
             )}
           >
-            <Spinner label={null} className={cn("block size-full", marker)} />
+            <Spinner
+              label={null}
+              className={cn("block size-full", marker, forcedMark)}
+            />
           </span>
         ) : (
           <span
@@ -253,6 +276,7 @@ export function Button(props: ButtonProps) {
               "marker-bar pointer-events-none absolute top-1/2 -translate-y-1/2",
               "transition-[clip-path,translate] duration-(--duration-base) ease-standard",
               markerBox[size],
+              forcedMark,
               disabled
                 ? "bg-on-disabled"
                 : [
@@ -276,7 +300,12 @@ export function Button(props: ButtonProps) {
               actionDivider[size],
               disabled
                 ? "bg-on-disabled/20"
-                : "bg-on-action/10 group-hover:bg-on-action/15 group-active:bg-on-action/20",
+                : [
+                    "bg-on-action/10 group-hover:bg-on-action/15 group-active:bg-on-action/20",
+                    // 悬停、按下那两档带着状态，优先级比单写的高：高对比模式下各写一份
+                    "forced-colors:group-hover:bg-[ButtonText] forced-colors:group-active:bg-[ButtonText]",
+                  ],
+              forcedMark,
             )}
           />
           {loading && (
@@ -286,7 +315,10 @@ export function Button(props: ButtonProps) {
                 actionSpinner[size],
               )}
             >
-              <Spinner label={null} className="block size-full" />
+              <Spinner
+                label={null}
+                className={cn("block size-full", forcedMark)}
+              />
             </span>
           )}
         </>

package/src/components/calendar/Calendar.tsx

@@ -1,6 +1,7 @@
 import {
   useEffect,
   useId,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -202,6 +203,37 @@ export function Calendar({
       ?.focus();
   }, [focused, month]);
 
+  // 翻月：新的一个月从翻的那一侧来。行是按日期当 key 的，相邻月份重叠的那几行是同一批元素
+  // （焦点靠这个留得住），所以不重挂——在日期那一块上标一下方向，撤了再标就重播
+  const turned = useRef({ month, until: 0, length: 0 });
+  useLayoutEffect(() => {
+    const last = turned.current;
+    if (last.month === month) return;
+    const forward = month > last.month;
+    last.month = month;
+    const grid = gridRef.current;
+    if (!grid) return;
+
+    const now = performance.now();
+    delete grid.dataset.turn;
+    // 上一次的还没播完又翻了（按住 PageDown、连点翻月钮）：这一次不播，直接换。
+    // 每次都从透明起的话，格子会一直闪。一直连着翻就一直不播
+    if (now < last.until) {
+      last.until = now + last.length;
+      return;
+    }
+    // 先让上一次的撤干净：同一个方向连着翻，标记没变也要重播
+    void grid.offsetWidth;
+    grid.dataset.turn = forward ? "next" : "previous";
+    // 多久算"还没播完"：问刚起的这一个动画，不另抄一份时长
+    const running =
+      typeof grid.getAnimations === "function"
+        ? grid.getAnimations()[0]
+        : undefined;
+    last.length = Number(running?.effect?.getComputedTiming().endTime ?? 0);
+    last.until = now + last.length;
+  }, [month]);
+
   const weeks = useMemo(
     () => monthGrid(month, weekStartsOn),
     [month, weekStartsOn],
@@ -331,6 +363,8 @@ export function Calendar({
         </thead>
         <tbody
           ref={gridRef}
+          // 翻月时从翻的那一侧来 8px 并淡入；方向标在 data-turn 上（见上面的 turned）
+          className="data-turn:animate-shift-in data-[turn=next]:[--shift-x:var(--motion-shift-lg)] data-[turn=previous]:[--shift-x:calc(var(--motion-shift-lg)*-1)]"
           onPointerLeave={() => setHovered(null)}
           onKeyDown={(event) => {
             // 起始日定了之后按 Esc：取消这一次，回到原来的那一段
@@ -400,10 +434,19 @@ export function Calendar({
                         "transition-colors duration-(--duration-fast) ease-standard",
                         focusRingInset,
                         endpoint
-                          ? "bg-surface-inverse font-bold text-ink-inverse"
+                          ? // 焦点环画在实心块里面：普通的焦点色在亮色下就是这块墨的颜色，
+                            // 暗色下是黄压在近白上，都看不见——换成反转块上的强调色。
+                            // 高对比模式下底色被系统换掉：实心块改用系统的"选中"色。
+                            // 这一格的颜色不让系统再改，不然它会在数字后面垫一块页面色。
+                            // 画在里面的焦点环换成它上面的字色，再往里收 2px——贴着边的话，
+                            // 环和页面一个颜色，看上去只是块小了一圈
+                            "bg-surface-inverse font-bold text-ink-inverse focus-visible:outline-accent-ink-inverse forced-colors:forced-color-adjust-none forced-colors:bg-[Highlight] forced-colors:text-[HighlightText] forced-colors:focus-visible:-outline-offset-4 forced-colors:focus-visible:outline-[HighlightText]"
                           : [
-                              // 一段的中间是连着的浅带；还没定结束日时是更浅的预览
-                              between ? "bg-ink/10" : previewing && "bg-ink/5",
+                              // 一段的中间是连着的浅带；还没定结束日时是更浅的预览。
+                              // 高对比模式下浅带没了，换成上下两条系统"选中"色的线——格子之间没有间距，连起来还是一条带子
+                              between
+                                ? "bg-ink/10 forced-colors:border-y-2 forced-colors:border-[Highlight]"
+                                : previewing && "bg-ink/5",
                               disabled
                                 ? "cursor-not-allowed text-ink-disabled line-through"
                                 : [
@@ -416,10 +459,11 @@ export function Calendar({
                         // 今天：数字下面一条短线，不只是换个字色
                         isToday &&
                           "after:absolute after:bottom-1.5 after:left-1/2 after:h-0.5 after:w-3 after:-translate-x-1/2 after:content-['']",
+                        // 高对比模式下这条线也是底色画的：换成所在那块底上的系统字色
                         isToday &&
                           (endpoint
-                            ? "after:bg-accent-ink-inverse"
-                            : "after:bg-accent-ink"),
+                            ? "after:bg-accent-ink-inverse forced-colors:after:bg-[HighlightText]"
+                            : "after:bg-accent-ink forced-colors:after:bg-[CanvasText]"),
                       )}
                     >
                       {dateParts(date).day}

package/src/components/checkbox/Checkbox.tsx

@@ -69,6 +69,7 @@ export function Checkbox({
               // 半选只属于复选框：一组单选都没选时也会命中 :indeterminate，
               // 所以这两个类不能放进与单选共用的 choiceBox
               "indeterminate:border-surface-inverse indeterminate:bg-surface-inverse",
+              "forced-colors:indeterminate:border-[Highlight] forced-colors:indeterminate:bg-[Highlight]",
               focusRing,
             )}
           />

package/src/components/checkbox/choice-style.ts

@@ -4,7 +4,7 @@
  */
 
 export const choiceLabel =
-  "group inline-flex min-h-10 items-start gap-2 py-2 text-base text-ink has-disabled:cursor-not-allowed has-disabled:text-ink-disabled";
+  "group inline-flex min-h-10 items-start gap-2 py-2 text-base text-ink has-disabled:cursor-not-allowed has-disabled:text-ink-disabled forced-colors:has-disabled:text-[GrayText]";
 
 /** 控件的定位盒：高度等于一行文字，标签换行时控件仍然对齐第一行 */
 export const choiceControl = "flex h-[1lh] shrink-0 items-center";
@@ -17,9 +17,14 @@ export const choiceControl = "flex h-[1lh] shrink-0 items-center";
  * 祖先上有 data-choice="diamond" 时换成菱形（方案 B）：方格缩到 14px 并转 45°，
  * 对角线正好还是 20px；未选是空心菱形，已选是实心的，不再画对勾和圆点——
  * 所以禁用的"已选"也要保持实心，否则和"未选"分不出来。
+ *
+ * 高对比模式下底色都被系统换掉，反转块就没了：已选的改用系统的"选中"色，
+ * 记号用它上面的字色；禁用的用灰字色（菱形仍然是实心的）。
  */
-export const choiceBox =
-  "peer size-5 shrink-0 appearance-none border-2 choice-diamond:size-3.5 choice-diamond:rotate-45 choice-diamond:checked:disabled:bg-ink-disabled border-line-strong bg-surface-sunken transition-colors duration-(--duration-fast) ease-standard group-hover:border-ink-secondary checked:border-surface-inverse checked:bg-surface-inverse aria-invalid:border-danger disabled:cursor-not-allowed disabled:border-ink-disabled disabled:bg-surface-sunken";
+export const choiceBox = [
+  "peer size-5 shrink-0 appearance-none border-2 choice-diamond:size-3.5 choice-diamond:rotate-45 choice-diamond:checked:disabled:bg-ink-disabled border-line-strong bg-surface-sunken transition-colors duration-(--duration-fast) ease-standard group-hover:border-ink-secondary checked:border-surface-inverse checked:bg-surface-inverse aria-invalid:border-danger disabled:cursor-not-allowed disabled:border-ink-disabled disabled:bg-surface-sunken",
+  "forced-colors:checked:border-[Highlight] forced-colors:checked:bg-[Highlight] forced-colors:disabled:border-[GrayText] forced-colors:disabled:bg-[Canvas] forced-colors:choice-diamond:checked:disabled:bg-[GrayText]",
+].join(" ");
 
 /** 方格 / 圆的定位盒：菱形比它小一圈，所以居中 */
 export const choiceFrame =
@@ -30,4 +35,4 @@ export const choiceFrame =
  * 淡入淡出，和方格换底色的那一下同时走——底色有过渡而记号硬切，看起来是两件事
  */
 export const choiceMark =
-  "pointer-events-none absolute inset-0 m-auto text-accent-ink-inverse opacity-0 transition-opacity duration-(--duration-fast) ease-standard peer-disabled:text-ink-disabled";
+  "pointer-events-none absolute inset-0 m-auto text-accent-ink-inverse opacity-0 transition-opacity duration-(--duration-fast) ease-standard peer-disabled:text-ink-disabled forced-colors:text-[HighlightText] forced-colors:peer-disabled:text-[GrayText]";

package/src/components/chip/capsule-style.ts

@@ -13,10 +13,25 @@ export const capsuleSize: Record<CapsuleSize, string> = {
   md: "h-8 px-4 text-sm",
 };
 
+/*
+ * 高对比模式下底色被系统换掉、透明的边线也显了形，选中的和没选的就成了一个样子：
+ * 选中的改用系统的"选中"色（禁用的是灰字色），连边线、焦点环一起写明，
+ * 并且不让系统再改这一颗的颜色——不然它会在字后面垫一块页面色，把"选中"色盖掉。
+ */
+const forcedSelected =
+  "forced-colors:forced-color-adjust-none forced-colors:focus-visible:outline-[Highlight]";
+
 export const capsuleState = {
-  selected: "border-transparent bg-surface-inverse text-ink-inverse",
+  selected: [
+    "border-transparent bg-surface-inverse text-ink-inverse",
+    "forced-colors:border-[Highlight] forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]",
+    forcedSelected,
+  ].join(" "),
   rest: "border-line-strong text-ink hover:bg-ink/5",
   disabled: "cursor-not-allowed border-line text-ink-disabled",
-  selectedDisabled:
+  selectedDisabled: [
     "cursor-not-allowed border-transparent bg-disabled text-on-disabled",
-} as const;
+    "forced-colors:border-[GrayText] forced-colors:bg-[GrayText] forced-colors:text-[Canvas]",
+    forcedSelected,
+  ].join(" "),
+};

package/src/components/combobox/Combobox.tsx

@@ -151,6 +151,13 @@ const currentHighlighted: Record<MenuVariant, string> = {
   strong: "data-highlighted:bg-action-pressed",
 };
 
+/*
+ * 高对比模式下底色都被系统换掉，"移到了哪一项"就看不见了：给被移到的那一项画一圈
+ * 系统"选中"色的环，和菜单、下拉选择里键盘走到的那一项同一个样子（那边是真的焦点环）
+ */
+const highlightedForced =
+  "forced-colors:data-highlighted:outline-2 forced-colors:data-highlighted:-outline-offset-2 forced-colors:data-highlighted:outline-[Highlight]";
+
 const iconButton =
   "flex shrink-0 items-center justify-center self-stretch text-ink-secondary hover:text-ink disabled:cursor-not-allowed disabled:text-ink-disabled disabled:hover:text-ink-disabled";
 
@@ -240,6 +247,7 @@ export function Combobox(props: ComboboxProps) {
                   currentHighlighted[panelVariant],
                 ]
               : menuItemHover,
+          highlightedForced,
         )
       }
       render={
@@ -306,6 +314,8 @@ export function Combobox(props: ComboboxProps) {
                         valueChip,
                         "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus",
                         "data-disabled:text-ink-disabled",
+                        // 高对比模式：系统不知道这一块禁用了，字和那一圈线都写明灰字色
+                        "forced-colors:data-disabled:border-[GrayText] forced-colors:data-disabled:text-[GrayText]",
                         valueChipSize[size],
                       )}
                     >

package/src/components/completion-banner/CompletionBanner.tsx

@@ -1,5 +1,7 @@
 import type { ComponentProps, ElementType, ReactNode } from "react";
+import { useInView } from "../../hooks/useInView";
 import { cn } from "../../lib/cn";
+import { mergeRefs } from "../../lib/merge-refs";
 import { GhostText } from "../ghost-text/GhostText";
 
 export type CompletionBannerProps = Omit<ComponentProps<"div">, "title"> & {
@@ -13,6 +15,8 @@ export type CompletionBannerProps = Omit<ComponentProps<"div">, "title"> & {
   action?: ReactNode;
   /** 标题层级，默认 3（`<h3>`） */
   level?: 2 | 3 | 4 | 5 | 6;
+  /** 进入视口时播放一次入场：色带从左擦入，随后出字。默认开启 */
+  animate?: boolean;
 };
 
 /**
@@ -28,19 +32,28 @@ export function CompletionBanner({
   description,
   action,
   level = 3,
+  animate = true,
   className,
   children,
+  ref,
   ...props
 }: CompletionBannerProps) {
   const Heading: ElementType = `h${level}`;
+  const [inViewRef, inView] = useInView<HTMLDivElement>({ disabled: !animate });
+  // 入场：整块从左擦入（背后的描边词在右下角，自然最后露出来），字和按钮等色带过去了再出
+  const pending = animate && !inView;
+  const playing = animate && inView;
 
   return (
     <div
       role="status"
       data-theme="inverse"
       {...props}
+      ref={mergeRefs(inViewRef, ref)}
       className={cn(
         "@container relative isolate overflow-clip bg-surface text-ink",
+        pending && "[clip-path:inset(0_100%_0_0)]",
+        playing && "animate-wipe-in",
         className,
       )}
     >
@@ -56,7 +69,13 @@ export function CompletionBanner({
       )}
       <div className="flex flex-wrap items-center justify-between gap-x-6 gap-y-3 px-4 py-4 @md:px-6 @md:py-5">
         {/* 强调色跟着这块底走：亮色页面上是黄字压墨底，暗色页面上是深黄字压近白底 */}
-        <div className="min-w-0 border-l-4 border-accent-ink pl-3">
+        <div
+          className={cn(
+            "min-w-0 border-l-4 border-accent-ink pl-3",
+            playing &&
+              "animate-shift-in [animation-delay:200ms] [--shift-x:calc(var(--motion-shift-lg)*-1)]",
+          )}
+        >
           <Heading className="text-lg font-bold wrap-anywhere text-accent-ink @md:text-xl">
             {title}
           </Heading>
@@ -65,7 +84,16 @@ export function CompletionBanner({
           )}
           {children}
         </div>
-        {action && <div className="shrink-0">{action}</div>}
+        {action && (
+          <div
+            className={cn(
+              "shrink-0",
+              playing && "animate-fade-in [animation-delay:200ms]",
+            )}
+          >
+            {action}
+          </div>
+        )}
       </div>
     </div>
   );

package/src/components/dash-indicator/DashIndicator.tsx

@@ -34,8 +34,11 @@ export function DashIndicator({
           data-current={position === current ? "" : undefined}
           className={cn(
             "h-0.5 transition-[width,background-color] duration-(--duration-base) ease-standard",
-            // 当前一根除了换色还加长一倍，不只靠颜色
-            position === current ? "w-8 bg-accent-ink" : "w-4 bg-line-strong",
+            // 当前一根除了换色还加长一倍，不只靠颜色。
+            // 高对比模式下底色被系统换掉，整排都没了：当前一根用系统的"选中"色，其余用页面的字色
+            position === current
+              ? "w-8 bg-accent-ink forced-colors:bg-[Highlight]"
+              : "w-4 bg-line-strong forced-colors:bg-[CanvasText]",
           )}
         />
       ))}

package/src/components/data-row/DataRow.tsx

@@ -167,7 +167,8 @@ const toneClass: Record<DataRowTone, string> = {
 };
 
 const favoriteDot = "block size-4 rounded-full";
-const favoriteOn = "bg-action";
+/* 高对比模式下底色被系统换掉，实心的圆就没了：改用系统的"选中"色 */
+const favoriteOn = "bg-action forced-colors:bg-[Highlight]";
 /* 未收藏是一个空心的圆环：形状也不同，不只靠颜色 */
 const favoriteOff = "border-2 border-ink-tertiary";