@endfield-ui/react 0.2.0 → 1.0.0

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,14 +17,22 @@ 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 =
   "relative inline-flex size-5 items-center justify-center";
 
-/** 压在方格 / 圆正中的记号，默认透明，由 peer 的状态点亮 */
+/**
+ * 压在方格 / 圆正中的记号，默认透明，由 peer 的状态点亮。
+ * 淡入淡出，和方格换底色的那一下同时走——底色有过渡而记号硬切，看起来是两件事
+ */
 export const choiceMark =
-  "pointer-events-none absolute inset-0 m-auto text-accent-ink-inverse opacity-0 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/corner-brackets/CornerBrackets.tsx

@@ -20,6 +20,7 @@ const sizeClass: Record<CornerBracketsSize, string> = {
  * 用于矩阵里的单选（物品格、名册卡、图鉴）；列表行用左缘色条，页签用底色，都不用它。
  *
  * 括号画在盒子之外 4px：它所在的容器不能贴着盒子裁切。
+ * 出现时八段短线从角的顶点伸到满长（200ms），消失是直接消失。
  * 括号只是给眼睛看的，选中态另外要有 `aria-selected` / `aria-pressed`。
  */
 export function CornerBrackets({
@@ -34,7 +35,7 @@ export function CornerBrackets({
       data-visible={visible ? "" : undefined}
       className={cn(
         "relative",
-        visible && "corner-brackets",
+        visible && "corner-brackets after:animate-bracket-in",
         sizeClass[size],
         className,
       )}

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";
 

package/src/components/date-picker/DateField.tsx

@@ -123,7 +123,11 @@ export function DateField({
             size={iconSize}
             className={cn(
               "shrink-0",
-              disabled ? "text-ink-disabled" : "text-ink-secondary",
+              // 高对比模式：写在 <svg> 自己身上的颜色系统不换（它只替图标换继承来的字色），
+              // 主题里的灰会原样压在使用者定的页面色上。写明系统色，和按钮里的字一起走
+              disabled
+                ? "text-ink-disabled forced-colors:text-[GrayText]"
+                : "text-ink-secondary forced-colors:text-[ButtonText]",
             )}
           />
         </BasePopover.Trigger>

package/src/components/dialog/Dialog.tsx

@@ -116,8 +116,10 @@ export function Dialog({
             className={cn(
               overlaySurface,
               "relative flex max-h-full min-h-0 w-full flex-col",
-              "transition-[scale,opacity] duration-(--duration-base) ease-exit",
-              "data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+              // 进场：淡入（200ms），同时从下面升上来 8px（300ms）。退场只淡出——位移只写在起点上。
+              // 不放大：这套语言里没有东西是"变大着出来"的
+              "transition-[opacity,translate] duration-[var(--duration-fast),var(--duration-base)] ease-[var(--ease-standard),var(--ease-exit)]",
+              "data-ending-style:opacity-0 data-starting-style:translate-y-(--motion-shift-lg) data-starting-style:opacity-0",
               sizeClass[size],
               className,
             )}