@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/auto-complete/auto-complete.tsx

@@ -1,7 +1,18 @@
 import * as React from 'react';
 
-import { cn } from '@/utils/cn';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandList,
+} from '@/components/command/command';
 import { Input } from '@/components/input/input';
+import {
+  Popover,
+  PopoverAnchor,
+  PopoverContent,
+} from '@/components/popover/popover';
 
 export interface AutoCompleteOption {
   /** 真实写入到输入框的 value(也作为建议列表 key)。 */
@@ -29,6 +40,7 @@ export interface AutoCompleteProps
   onChange?: (value: string) => void;
   /**
    * 用户输入时回调,用于刷新 `options`(异步建议)。
+   * 提供该回调后,内部不再对 `options` 做本地过滤(由外部按 query 自行刷新)。
    */
   onSearch?: (query: string) => void;
   /**
@@ -47,15 +59,23 @@ export interface AutoCompleteProps
   emptyText?: string;
   /**
    * 容器尺寸 — 透传 Input.size。
-   * @default "default"
+   * @default "md"
    */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
+  /**
+   * 错误态视觉(校验失败) — 透传给内部 Input,红色 border + ring,自动写 `aria-invalid="true"`。
+   * @default false
+   */
+  error?: boolean;
 }
 
 /**
  * 输入即建议 — antd 独有补足。**等价 antd `AutoComplete`**。
- * 与 `Combobox` 区别:Combobox 是"必选下拉",输入框只接受选项中的值;
- * AutoComplete 是"自由输入 + 选项建议",最终 value 可以是任意字符串。
+ *
+ * 与 `Combobox` 区别:Combobox 是"必选下拉",输入框只接受选项中的值(closed-list);
+ * AutoComplete 是"自由输入 + 选项建议",最终 value 可以是任意字符串(open-list)。
+ *
+ * 内核与 `Select` 同源 —— 基于 `Popover + cmdk Command`,共享下拉视觉、键盘导航与 a11y。
  */
 const AutoComplete = React.forwardRef<HTMLInputElement, AutoCompleteProps>(
   (
@@ -68,7 +88,8 @@ const AutoComplete = React.forwardRef<HTMLInputElement, AutoCompleteProps>(
       onSelect,
       openOnFocus = false,
       emptyText = '无匹配项',
-      size = 'default',
+      size = 'md',
+      error = false,
       className,
       onFocus,
       onBlur,
@@ -84,18 +105,22 @@ const AutoComplete = React.forwardRef<HTMLInputElement, AutoCompleteProps>(
     const current = isControlled ? value! : internal;
 
     const [open, setOpen] = React.useState(false);
-    const [activeIdx, setActiveIdx] = React.useState(0);
+    const [activeValue, setActiveValue] = React.useState<string>('');
 
+    // 提供 onSearch 时,默认认为外部按 query 异步刷过 options;否则内部本地过滤
     const filtered = React.useMemo(() => {
+      if (onSearch) return options;
       const q = current.toLowerCase();
       return q === ''
         ? options
         : options.filter((o) => o.value.toLowerCase().includes(q));
-    }, [current, options]);
+    }, [current, options, onSearch]);
 
+    // filtered 变化时,默认高亮第一个可用项
     React.useEffect(() => {
-      setActiveIdx(0);
-    }, [current]);
+      const first = filtered.find((o) => !o.disabled);
+      setActiveValue(first?.value ?? '');
+    }, [filtered]);
 
     const update = (next: string) => {
       if (!isControlled) setInternal(next);
@@ -109,20 +134,30 @@ const AutoComplete = React.forwardRef<HTMLInputElement, AutoCompleteProps>(
       setOpen(false);
     };
 
+    const moveActive = (dir: 1 | -1) => {
+      const enabled = filtered.filter((o) => !o.disabled);
+      if (enabled.length === 0) return;
+      const idx = enabled.findIndex((o) => o.value === activeValue);
+      const nextIdx =
+        (idx === -1 ? 0 : idx + dir + enabled.length) % enabled.length;
+      const nextOpt = enabled[nextIdx];
+      if (nextOpt) setActiveValue(nextOpt.value);
+    };
+
     const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
-      if (open && filtered.length > 0) {
+      if (open) {
         if (e.key === 'ArrowDown') {
           e.preventDefault();
-          setActiveIdx((i) => (i + 1) % filtered.length);
+          moveActive(1);
           return;
         }
         if (e.key === 'ArrowUp') {
           e.preventDefault();
-          setActiveIdx((i) => (i - 1 + filtered.length) % filtered.length);
+          moveActive(-1);
           return;
         }
         if (e.key === 'Enter') {
-          const opt = filtered[activeIdx];
+          const opt = filtered.find((o) => o.value === activeValue);
           if (opt && !opt.disabled) {
             e.preventDefault();
             select(opt);
@@ -134,69 +169,82 @@ const AutoComplete = React.forwardRef<HTMLInputElement, AutoCompleteProps>(
           setOpen(false);
           return;
         }
+      } else if (e.key === 'ArrowDown' && filtered.length > 0) {
+        e.preventDefault();
+        setOpen(true);
+        return;
       }
       onKeyDown?.(e);
     };
 
-    const shouldShow = open && (filtered.length > 0 || current !== '');
-
     return (
-      <div className={cn('relative', className)}>
-        <Input
-          ref={ref}
-          value={current}
-          placeholder={placeholder}
-          disabled={disabled}
-          size={size}
-          onChange={(e) => {
-            update(e.target.value);
-            onSearch?.(e.target.value);
-            setOpen(true);
-          }}
-          onFocus={(e) => {
-            if (openOnFocus) setOpen(true);
-            onFocus?.(e);
-          }}
-          onBlur={(e) => {
-            window.setTimeout(() => setOpen(false), 120);
-            onBlur?.(e);
-          }}
-          onKeyDown={handleKeyDown}
-          {...props}
-        />
-        {shouldShow ? (
-          <ul
-            role="listbox"
-            className="absolute left-0 right-0 top-full z-50 mt-1 max-h-60 overflow-auto rounded-md border bg-popover p-1 text-sm text-popover-foreground shadow-md"
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverAnchor asChild>
+          <Input
+            ref={ref}
+            value={current}
+            placeholder={placeholder}
+            disabled={disabled}
+            size={size}
+            error={error}
+            className={className}
+            role="combobox"
+            aria-autocomplete="list"
+            aria-expanded={open}
+            onChange={(e) => {
+              const next = e.target.value;
+              update(next);
+              onSearch?.(next);
+              setOpen(true);
+            }}
+            onFocus={(e) => {
+              if (openOnFocus) setOpen(true);
+              onFocus?.(e);
+            }}
+            onBlur={(e) => {
+              window.setTimeout(() => setOpen(false), 120);
+              onBlur?.(e);
+            }}
+            onKeyDown={handleKeyDown}
+            {...props}
+          />
+        </PopoverAnchor>
+        <PopoverContent
+          align="start"
+          sideOffset={4}
+          onOpenAutoFocus={(e) => e.preventDefault()}
+          // 读 Radix 暴露的 CSS 变量让弹层宽度追平 Input 宽度;主动选 style 而非 Tailwind
+          // arbitrary value(`w-[var(--...)]`),避免 `teamix-evo/no-arbitrary-tw-value` lint 告警
+          style={{ width: 'var(--radix-popover-trigger-width)' }}
+          className="p-0"
+        >
+          <Command
+            shouldFilter={false}
+            value={activeValue}
+            onValueChange={setActiveValue}
           >
-            {filtered.length === 0 ? (
-              <li className="px-2 py-1.5 text-center text-xs text-muted-foreground">
-                {emptyText}
-              </li>
-            ) : (
-              filtered.map((opt, i) => (
-                <li
-                  key={opt.value}
-                  role="option"
-                  aria-selected={i === activeIdx}
-                  onMouseDown={(e) => {
-                    e.preventDefault();
-                    select(opt);
-                  }}
-                  onMouseEnter={() => setActiveIdx(i)}
-                  className={cn(
-                    'cursor-pointer rounded-sm px-2 py-1.5',
-                    i === activeIdx && !opt.disabled && 'bg-accent text-accent-foreground',
-                    opt.disabled && 'cursor-not-allowed opacity-50',
-                  )}
-                >
-                  {opt.label ?? opt.value}
-                </li>
-              ))
-            )}
-          </ul>
-        ) : null}
-      </div>
+            <CommandList>
+              <CommandEmpty>{emptyText}</CommandEmpty>
+              {filtered.length > 0 && (
+                <CommandGroup>
+                  {filtered.map((opt) => (
+                    <CommandItem
+                      key={opt.value}
+                      value={opt.value}
+                      disabled={opt.disabled}
+                      onSelect={() => select(opt)}
+                      // 阻止鼠标按下时让 Input 失焦,避免选中前 popover 已关闭
+                      onMouseDown={(e) => e.preventDefault()}
+                    >
+                      {opt.label ?? opt.value}
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              )}
+            </CommandList>
+          </Command>
+        </PopoverContent>
+      </Popover>
     );
   },
 );

package/src/components/avatar/avatar.meta.md

@@ -1,13 +1,14 @@
 ---
 id: avatar
 name: Avatar
+displayName: 头像
 type: component
-category: foundation
+category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Avatar
+# Avatar 头像
 
 头像 — Radix Avatar(图片加载失败自动回退到 Fallback)+ antd Avatar 的 `size / shape / Avatar.Group` 并集。
 
@@ -29,7 +30,7 @@ package: "@teamix-evo/ui"
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `size` | `'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 尺寸(antd 并集:sm 32 / default 40 / lg 48 / xl 64)。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 尺寸(antd 并集:sm 32 / default 40 / lg 48 / xl 64)。 |
 | `shape` | `'circle' \| 'square'` | `"circle"` | – | 形状(antd 并集)。 |
 <!-- auto:props:end -->
 
@@ -51,12 +52,10 @@ package: "@teamix-evo/ui"
 > 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
 
 ```bash
-pnpm add @radix-ui/react-avatar@^1.1.0 class-variance-authority@^0.7.0
+pnpm add @radix-ui/react-avatar@^1.1.0 class-variance-authority@^0.7.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
-> 子组件:`AvatarImage`(图片源)/ `AvatarFallback`(加载失败 / 无图时的占位)/ `AvatarGroup`(多头像折叠组,带 `max` 与 `size`)。
-
 ## AI 生成纪律
 
 - **必须配 Fallback**:`AvatarImage` 加载失败时无 Fallback 会渲染空白;**永远**写 `<AvatarImage /> + <AvatarFallback>{initials}</AvatarFallback>` 的对子

package/src/components/avatar/avatar.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from './avatar';
 
 const meta: Meta<typeof Avatar> = {
-  title: '基础原语 · Foundation/Avatar',
+  title: '数据展示 · Data Display/Avatar',
   component: Avatar,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '头像 — 表示用户或对象，支持图片 / 文字 / 图标三种回退源。基于 Radix Avatar(图片加载失败自动回退到 fallback) + antd 增强:尺寸 sm/default/lg、形状 circle/square、`AvatarGroup` 堆叠。Image / Fallback 通过命名子组件组合。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '头像 — 表示用户或对象，支持图片 / 文字 / 图标三种回退源。基于 Radix Avatar（图片加载失败自动回退到 fallback）+ antd 增强：尺寸 sm/default/lg/xl、形状 circle/square、`AvatarGroup` 堆叠。未传 children 时 fallback 默认渲染 lucide `User` 占位图标。',
       },
     },
   },
@@ -66,6 +66,24 @@ export const FallbackOnly: Story = {
   ),
 };
 
+export const DefaultIconFallback: Story = {
+  name: '默认图标回退',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-end gap-3">
+      {(['sm', 'default', 'lg', 'xl'] as const).map((s) => (
+        <Avatar key={s} size={s}>
+          {/* 未传图片与文字 children, fallback 自动渲染 lucide User 占位 */}
+          <AvatarFallback />
+        </Avatar>
+      ))}
+      <Avatar shape="square">
+        <AvatarFallback />
+      </Avatar>
+    </div>
+  ),
+};
+
 export const Group: Story = {
   parameters: { controls: { disable: true } },
   render: () => (

package/src/components/avatar/avatar.tsx

@@ -1,27 +1,26 @@
 import * as React from 'react';
 import * as AvatarPrimitive from '@radix-ui/react-avatar';
 import { cva, type VariantProps } from 'class-variance-authority';
+import { User } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 
-const avatarVariants = cva(
-  'relative flex shrink-0 overflow-hidden bg-muted',
-  {
-    variants: {
-      size: {
-        sm: 'size-8 text-xs',
-        default: 'size-10 text-sm',
-        lg: 'size-12 text-base',
-        xl: 'size-16 text-lg',
-      },
-      shape: {
-        circle: 'rounded-full',
-        square: 'rounded-md',
-      },
+const avatarVariants = cva('relative flex shrink-0 overflow-hidden bg-muted', {
+  variants: {
+    size: {
+      sm: 'size-8 text-xs',
+      md: 'size-10 text-xs',
+      default: 'size-10 text-xs',
+      lg: 'size-12 text-sm',
+      xl: 'size-16 text-base',
+    },
+    shape: {
+      circle: 'rounded-full',
+      square: 'rounded-md',
     },
-    defaultVariants: { size: 'default', shape: 'circle' },
   },
-);
+  defaultVariants: { size: 'md', shape: 'circle' },
+});
 
 export interface AvatarProps
   extends React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>,
@@ -30,7 +29,7 @@ export interface AvatarProps
    * 尺寸(antd 并集:sm 32 / default 40 / lg 48 / xl 64)。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg' | 'xl';
+  size?: 'sm' | 'md' | 'default' | 'lg' | 'xl';
   /**
    * 形状(antd 并集)。
    * @default "circle"
@@ -65,7 +64,7 @@ AvatarImage.displayName = AvatarPrimitive.Image.displayName;
 const AvatarFallback = React.forwardRef<
   React.ElementRef<typeof AvatarPrimitive.Fallback>,
   React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Fallback>
->(({ className, ...props }, ref) => (
+>(({ className, children, ...props }, ref) => (
   <AvatarPrimitive.Fallback
     ref={ref}
     className={cn(
@@ -73,7 +72,9 @@ const AvatarFallback = React.forwardRef<
       className,
     )}
     {...props}
-  />
+  >
+    {children ?? <User className="h-3/5 w-3/5" aria-hidden="true" />}
+  </AvatarPrimitive.Fallback>
 ));
 AvatarFallback.displayName = AvatarPrimitive.Fallback.displayName;
 
@@ -106,10 +107,10 @@ const AvatarGroup = React.forwardRef<HTMLDivElement, AvatarGroupProps>(
       >
         {visible.map((child, i) =>
           React.isValidElement(child) && size
-            ? React.cloneElement(
-                child as React.ReactElement<AvatarProps>,
-                { size, key: i },
-              )
+            ? React.cloneElement(child as React.ReactElement<AvatarProps>, {
+                size,
+                key: i,
+              })
             : child,
         )}
         {overflow > 0 ? (

package/src/components/badge/badge.meta.md

@@ -1,23 +1,24 @@
 ---
 id: badge
 name: Badge
+displayName: 徽标
 type: component
-category: foundation
+category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Badge
+# Badge 徽标
 
 徽标 — shadcn 文本标签风格 + antd 数字徽标 / 红点 / 状态点的合集。
 **单组件四种形态**,根据 props 自动切换:
 
-| 形态 | 触发条件 | 示例 |
-| --- | --- | --- |
-| 文本徽标(shadcn) | 无 `count / dot / status`,仅 `children` | `<Badge>New</Badge>` |
-| 包裹徽标(antd) | 有 `children` + `count` 或 `dot` | `<Badge count={5}><Avatar /></Badge>` |
-| 独立数字气泡 | 仅 `count`,无 `children` | `<Badge count={3} />` |
-| 状态点 + 文字 | 有 `status` | `<Badge status="success" text="运行中" />` |
+| 形态             | 触发条件                                | 示例                                       |
+| ---------------- | --------------------------------------- | ------------------------------------------ |
+| 文本徽标(shadcn) | 无 `count / dot / status`,仅 `children` | `<Badge>New</Badge>`                       |
+| 包裹徽标(antd)   | 有 `children` + `count` 或 `dot`        | `<Badge count={5}><Avatar /></Badge>`      |
+| 独立数字气泡     | 仅 `count`,无 `children`                | `<Badge count={3} />`                      |
+| 状态点 + 文字    | 有 `status`                             | `<Badge status="success" text="运行中" />` |
 
 ## When to use
 

package/src/components/badge/badge.stories.tsx

@@ -1,9 +1,9 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Bell, MessageSquare, ShoppingCart } from 'lucide-react';
 import { Badge } from './badge';
 
 const meta: Meta<typeof Badge> = {
-  title: '基础原语 · Foundation/Badge',
+  title: '数据展示 · Data Display/Badge',
   component: Badge,
   tags: ['autodocs'],
   parameters: {

package/src/components/badge/badge.tsx

@@ -4,7 +4,7 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '@/utils/cn';
 
 const badgeVariants = cva(
-  'inline-flex items-center rounded-md border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2',
+  'inline-flex items-center rounded-md border border-border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2',
   {
     variants: {
       variant: {
@@ -16,9 +16,9 @@ const badgeVariants = cva(
           'border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80',
         outline: 'text-foreground',
         success:
-          'border-transparent bg-emerald-500 text-white hover:bg-emerald-500/80',
+          'border-transparent bg-success text-success-foreground hover:bg-success/80',
         warning:
-          'border-transparent bg-amber-500 text-white hover:bg-amber-500/80',
+          'border-transparent bg-warning text-warning-foreground hover:bg-warning/80',
       },
     },
     defaultVariants: {
@@ -27,18 +27,12 @@ const badgeVariants = cva(
   },
 );
 
-/**
- * 状态点的语义色映射。来自 design `foundations/color/semantic.md`。
- * 之所以这里硬编码 hex/tailwind class 而非 design token,
- * 是因为 status 是数值化状态枚举(antd 体系),需要稳定一对一映射;
- * 切换 design variant 时通过 token 层调整这些颜色,而非组件层。
- */
 const statusDotClasses: Record<BadgeStatus, string> = {
   default: 'bg-muted-foreground',
-  success: 'bg-emerald-500',
-  processing: 'bg-blue-500',
+  success: 'bg-success',
+  processing: 'bg-info',
   error: 'bg-destructive',
-  warning: 'bg-amber-500',
+  warning: 'bg-warning',
 };
 
 export type BadgeStatus =
@@ -119,7 +113,7 @@ const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
       return (
         <span
           ref={ref}
-          className={cn('inline-flex items-center gap-2 text-sm', className)}
+          className={cn('inline-flex items-center gap-2 text-xs', className)}
           {...props}
         >
           <span
@@ -154,7 +148,7 @@ const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
               aria-hidden="true"
             />
           ) : (
-            <span className="absolute right-0 top-0 inline-flex min-w-[1.25rem] -translate-y-1/2 translate-x-1/2 items-center justify-center rounded-full bg-destructive px-1 text-[10px] font-semibold leading-none text-destructive-foreground ring-2 ring-background">
+            <span className="absolute right-0 top-0 inline-flex h-5 min-w-counter -translate-y-1/2 translate-x-1/2 items-center justify-center rounded-full bg-destructive px-1.5 text-xs font-semibold leading-none text-destructive-foreground ring-2 ring-background">
               {display}
             </span>
           )}
@@ -183,7 +177,7 @@ const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
         <span
           ref={ref}
           className={cn(
-            'inline-flex min-w-[1.25rem] items-center justify-center rounded-full bg-destructive px-1 text-[10px] font-semibold leading-none text-destructive-foreground',
+            'inline-flex h-5 min-w-counter items-center justify-center rounded-full bg-destructive px-1.5 text-xs font-semibold leading-none text-destructive-foreground',
             className,
           )}
           {...props}

package/src/components/breadcrumb/breadcrumb.meta.md

@@ -1,15 +1,17 @@
 ---
 id: breadcrumb
 name: Breadcrumb
+displayName: 面包屑
 type: component
 category: navigation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Breadcrumb
+# Breadcrumb 面包屑
+
+在多层级页面中显示当前位置并提供回溯路径。默认分隔符 lucide `ChevronRight`,字号 `text-sm`,普通项 `text-muted-foreground` / 当前项 `text-foreground` / 链接 hover 升至 `text-foreground`,能力 = shadcn 原子 ∪ antd `separator`,不收 antd `routes` / `itemRender`。
 
-面包屑 — 纯组合组件 + antd `separator` 自定义并集。
 **与 antd Breadcrumb 的差异**:antd 用 `routes` 数组配置;本组件走 shadcn 的**组合式**(每项手写 `<BreadcrumbItem>`),配 React Router / Next.js Link 时更灵活。
 
 ## When to use
@@ -31,7 +33,7 @@ package: "@teamix-evo/ui"
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `separator` | `React.ReactNode` | – | – | 自定义分隔符(antd `separator` 并集)。每个 `<BreadcrumbSeparator />` 默认渲染 `<ChevronRight />`, 通过设置 children 可全局覆盖。 |
+| `separator` | `React.ReactNode` | `<ChevronRight />` | – | 自定义全局分隔符(antd `separator` 并集)。仅作类型层占位 — 实际渲染由 `<BreadcrumbSeparator>` 控制,默认 lucide `ChevronRight`, 通过 `<BreadcrumbSeparator>{节点}</BreadcrumbSeparator>` 覆盖单个分隔符。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -56,16 +58,34 @@ pnpm add @radix-ui/react-slot@^1.1.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
-> 子组件:`Breadcrumb`(nav)/ `BreadcrumbList`(ol)/ `BreadcrumbItem`(li)/ `BreadcrumbLink`(支持 asChild)/ `BreadcrumbPage`(当前页,不可点)/ `BreadcrumbSeparator`(默认 ChevronRight,可自定义)/ `BreadcrumbEllipsis`(省略,中间路径折叠用)。
-
 ## AI 生成纪律
 
+- **默认分隔符是箭头**(`ChevronRight`),不要手写 `/` / `>` / `·` 字符 — 需覆盖时传入 `<BreadcrumbSeparator>{customNode}</BreadcrumbSeparator>`
+- **字号走 token**:所有项默认 `text-sm`(14px),不要在业务层覆写 `text-base` / `text-xs`,跨面包屑不一致会破坏顶部导航识别度
+- **颜色走 semantic**:普通项 `text-muted-foreground` / 当前项 `text-foreground` / 链接 hover 升至 `text-foreground`。不要用 `text-primary` / `text-blue-*` 手动上色
 - **当前页用 `BreadcrumbPage`**,不是 `BreadcrumbLink`(语义 + 视觉都不同)
 - **配路由用 `asChild`**:`<BreadcrumbLink asChild><Link to="/x">...</Link></BreadcrumbLink>`
-- **每两项之间必有 Separator**:不要手写 `>` 字符
+- **每两项之间必有 Separator**:不要手写文本分隔
 - **过长路径用 Ellipsis**:超过 4 级时中间收成 `<BreadcrumbEllipsis />`(可配 DropdownMenu 展开完整列表)
 - **路径文字简短**:每段 ≤ 6 字 / 12 字符,过长导致换行视觉破碎
 
+## Breadcrumb 形态 — 旧库 API → 新库映射
+
+旧库(Teamix 1.0 / `@alifd/next`)走数据驱动的 `Breadcrumb.Item` + `maxNode`,新库走 shadcn 的**纯组合**(`BreadcrumbList` / `BreadcrumbItem` / `BreadcrumbLink` / `BreadcrumbPage` / `BreadcrumbSeparator` / `BreadcrumbEllipsis`)。下表给出旧库 API 到新库写法的逐项映射。
+
+| 旧库 API | 新库写法 | 备注 |
+| --- | --- | --- |
+| `<Breadcrumb>` 容器 | `<Breadcrumb><BreadcrumbList>...</BreadcrumbList></Breadcrumb>` | 容器 + List 双层是 `nav > ol` 语义,无障碍更准 |
+| `<Breadcrumb.Item link="/x">label</Breadcrumb.Item>` | `<BreadcrumbItem><BreadcrumbLink href="/x">label</BreadcrumbLink></BreadcrumbItem>` | Item 与 Link 拆开,Link 可单独控制 hover / focus 样式 |
+| 末项(当前页) | `<BreadcrumbItem><BreadcrumbPage>label</BreadcrumbPage></BreadcrumbItem>` | `aria-current="page"` 自动注入 |
+| `separator="/"` | `<BreadcrumbSeparator>{customNode}</BreadcrumbSeparator>` | 默认 lucide `ChevronRight`,组件化覆盖更可控 |
+| `maxNode={3}` 自动折叠 | 业务自切片 + `<BreadcrumbEllipsis />` 配 `<DropdownMenu>` 弹出 | 见 `MaxNodeCollapse` Story —— 折叠 UI 完全由你控制(Dropdown / Tooltip / Popover 任选) |
+| `showHiddenItems` 弹层展开 | 同上,用 `<DropdownMenu>` 触发器包 `<BreadcrumbEllipsis />` | — |
+| `popupContainer` / `popupProps` | DropdownMenu 自身的 `modal` / `onOpenChange` | 弹层细节转交 DropdownMenu |
+| `component="span"` 自定义根标签 | 不修复 — 固定 `<nav>`(无障碍语义) | — |
+| `prefix` CSS 前缀 | 不修复 — Tailwind 无 CSS prefix 概念 | — |
+| 路由集成 | `<BreadcrumbLink asChild><Link to="/x">...</Link></BreadcrumbLink>` | shadcn 的 `asChild`(Slot),适配任意路由组件 |
+
 ## Examples
 
 ```tsx