@teamix-evo/ui

Source-injected UI components for Teamix Evo. Based on shadcn/ui, extended with antd-level capabilities (loading / icon / shape / block / dashed variant). Components are written as ready-to-use React source code; users install components via teamix-evo ui add <id>, the source is written to their project, and they own the code.

🤖 Working on this package? Read AGENTS.md (and CLAUDE.md) before adding or changing components. They lay out the design-philosophy references (@teamix-evo/tokens's OpenTrek system), the AI compliance checklist, and the ui-side engineering constraints. New components MUST follow that guide.

Architecture

• Source injection: components ship as .tsx files, not as a runtime library. npx teamix-evo ui add button copies button.tsx into the user project under aliases.components.
• First consumer of @teamix-evo/tokens: the dev server imports OpenTrek tokens directly from the tokens package (dev/index.css), so components are previewed against the SAME tokens that ship to consumers — no mock values, single source of truth.
• No variant: brand differences are absorbed by @teamix-evo/tokens (CSS variables). One UI package serves all design variants.
• className contract: components write className="bg-primary" (Tailwind v4 utility), which resolves to var(--color-primary) from the project's tokens.theme.css. Semantic token names (primary, destructive, muted, ...) align with shadcn — see @teamix-evo/tokens for the token layer.
• Imports: source files use real alias paths (e.g. @/lib/utils, @/components/button) that match the default user aliases. The CLI's rewriteImports keeps them aligned with aliases declared in .teamix-evo/config.json at install time.
• updateStrategy: frozen is the default — once installed, the CLI never overwrites the file. Upgrades go through an AI + skill flow (v0.3, see PLAN §10.9).

Package layout

packages/ui/
├── manifest.json          # UiPackageManifest (flat entries, no variant)
├── _data.json             # Package-level metadata (default iconLibrary, aliases)
├── tsconfig.json
├── vite.config.ts         # alias plugin (auto-picked by Storybook react-vite)
├── .storybook/            # Storybook 8 config + globals.css importing design tokens
│   ├── main.ts
│   ├── preview.ts
│   └── globals.css
├── scripts/
│   ├── validate-entries.ts
│   └── generate-meta.ts   # ts-morph → Props table inside meta.md marker region
└── src/
    ├── components/
    │   └── button/
    │       ├── button.tsx
    │       ├── button.meta.md    # AI-readable component intro (Props auto-generated)
    │       └── button.stories.tsx (CSF 3.0)
    └── lib/
        ├── utils.ts        ← cn() helper
        └── color.ts       ← Color util

Scripts

• pnpm validate — schema check + source path existence + dependency-graph soundness
• pnpm typecheck — tsc --noEmit over src and .storybook
• pnpm storybook — open Storybook 8 dev server (auto-loads OpenTrek tokens via .storybook/globals.css)
• pnpm build-storybook — produce static docs site under storybook-static/
• pnpm gen:meta — regenerate <id>.meta.md Props tables from source JSDoc (ts-morph)
• pnpm gen:check — verify meta tables are in sync (used in CI)

Adding a new entry

1. Create the source file(s) under src/components/<id>/ (or src/hooks/, src/utils/, ...)
2. Append an entry to manifest.json with id, type, files[], meta?, registryDependencies?, dependencies?
3. Run pnpm validate

Each component should ship a <id>.meta.md (frontmatter + Markdown). MCP reads it directly from @teamix-evo/ui at runtime — no consumer-side copy is written (per ADR 0020 §3).

Component Matrix (91 entries · 90 components + 1 util)

2026-05-16 校准 manifest.json,覆盖 shadcn 60 件 ∪ antd v6 60 件 的高频与中频集。

来源标记:

• 🅢 shadcn 原生 / shadcn 2025-10 新增原子(antd 体系无对应或仅有装饰对应)
• 🅐 antd 独有补足(shadcn 体系无)
• 🅢🅐 两边都有,本库交付功能并集(能力 = shadcn ∪ antd)

1. 基础原语 / Foundation(13 件)

零依赖或仅依赖 cn,被后续大量组件依赖。

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | -------------------------------------------- | ------------ | ----------- | ---- | ------------------------------------------------------------------------------- | | cn | 类名合并工具 | cn | util | clsx + tailwind-merge,所有组件的 className 合并基础 | | button | 按钮 | Button | 🅢🅐 | shadcn Button + antd loading / icon / shape / block / dashed variant | | label | 表单标签 | Label | 🅢 | Radix Label,补 required / disabled 显式视觉(对齐 antd Form.Item label 部分) | | badge | 徽标 | Badge | 🅢🅐 | 四种形态:文本徽标 / 数字气泡 / 红点 / 状态点(对齐 antd Badge) | | separator | 分隔线 | Separator | 🅢🅐 | shadcn Separator + antd Divider 的 dashed / 中间装饰文本 | | skeleton | 骨架屏 | Skeleton | 🅢🅐 | shadcn pulse + antd Avatar/Image/Button/Input/Paragraph 子家族 | | avatar | 头像 | Avatar | 🅢🅐 | Radix Avatar + antd size / shape / Avatar.Group | | progress | 进度条 | Progress | 🅢🅐 | 线形 + 配套 ProgressCircle 环形(对齐 antd Progress) | | spinner | 加载指示器 | Spinner | 🅢🅐 | shadcn 2025-10 新增;4 档尺寸 + 4 档语义色(对齐 antd Spin 无遮罩版) | | aspect-ratio | 等比容器 | AspectRatio | 🅢 | Radix AspectRatio,无 layout shift(antd 体系无) | | image | 图片 | Image | 🅐 | 自动加载占位 + 失败占位 + 点击预览(对齐 antd Image) | | tag | 标签 | Tag | 🅐 | 关键词标签 + closable + 6 种语义色 + CheckableTag(Group)(对齐 antd Tag v6) |

2. 布局与容器 / Layout & Container(8 件)

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | -------------------------------------------- | ---------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | | flex | 弹性布局 | Flex | 🅐 | Tailwind flex 语义封装,as 语义标签 + inline + split——一个原子覆盖布局容器与 inline 小集合(等价 antd Flex v5.10+ ∪ Space) | | grid | 栅格 | Grid (Row + Col) | 🅐 | 24 栅格,CSS Grid 实现(对齐 antd Row + Col) | | masonry | 瀑布流 | Masonry | 🅐 | CSS column-count 0 JS 实现(对齐 antd Masonry v6.0) | | scroll-area | 滚动容器 | ScrollArea | 🅢 | Radix ScrollArea,跨浏览器一致滚动条(antd 体系无) | | resizable | 可拖拽分栏 | Resizable | 🅢🅐 | react-resizable-panels,VS Code / Figma 风格(对齐 antd Splitter v5.21+) | | card | 卡片 | Card | 🅢🅐 | + hoverable / loading / Cover / Actions / Meta / CardAction(2026-04 shadcn 新增子组件) | | item | 列表项 | Item | 🅢 | shadcn 2025-10 新增;5 槽 Media/Content/Title/Description/Actions + ItemGroup(替代旧 List.Item) | | descriptions | 描述列表 | Descriptions | 🅐 | 键值对详情,items 数组驱动,bordered / span(对齐 antd Descriptions) |

3. 表单与输入 / Form & Input(28 件)

3.1 表单组装

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | -------------------------------------------- | -------- | ----------- | ---- | ------------------------------------------------------------------------- | | form | 表单 | Form | 🅢🅐 | react-hook-form + zod + shadcn 7 件套(对齐 antd Form) | | field | 字段抽象 | Field | 🅢 | shadcn 2025-10 新增;7 槽,可搭任何状态管理(对齐 antd Form.Item 的解耦版) | | input-group | 输入框组 | InputGroup | 🅢 | shadcn 2025-10 新增;复合插槽(对齐 antd Input 的 prefix/suffix/addon 集合) | | button-group | 按钮组 | ButtonGroup | 🅢🅐 | shadcn 2025-10 新增;Split Button / Toolbar(对齐 antd Space.Compact v6) |

3.2 文本类输入

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | -------------------------------------------- | ---------- | ----------- | ---- | ------------------------------------------------------------------------------------------------------------- | | input | 输入框 | Input | 🅢🅐 | + clearable / showCount / size / error 四档内建(复合形态已拆出独立 InputGroup,对齐 antd Input 集合) | | textarea | 多行文本框 | Textarea | 🅢🅐 | + autoSize / showCount(对齐 antd Input.TextArea) | | input-number | 数字输入框 | InputNumber | 🅐 | 步进 + min/max 夹紧 + precision + 千分位 + null 空状态(对齐 antd InputNumber) | | mentions | @ 提及输入 | Mentions | 🅐 | Textarea + @ 触发候选下拉,异步 onSearch(对齐 antd Mentions) |

3.3 选择类(下拉 / 单选 / 多选)

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | ---------------------------------------------- | ---------- | ------------ | ---- | ----------------------------------------------------------------------- | | select | 选择器 | Select | 🅢🅐 | Radix Select(对齐 antd Select 单选) | | native-select | 原生选择器 | NativeSelect | 🅢 | shadcn 2025-10 新增;原生 <select>,移动端 / SSR 友好(antd 体系无) | | auto-complete | 自动完成 | AutoComplete | 🅐 | 自由输入 + 候选建议(value 可任意 string)(对齐 antd AutoComplete) | | cascader | 级联选择 | Cascader | 🅐 | 多级联动,叶子触发 / 中途可选(对齐 antd Cascader) | | tree-select | 树形选择 | TreeSelect | 🅐 | Tree 嵌入 Popover,单选 / 多选(对齐 antd TreeSelect) | | checkbox | 多选框 | Checkbox | 🅢🅐 | Radix 原生 indeterminate + Checkbox.Group(对齐 antd Checkbox) | | radio-group | 单选组 | RadioGroup | 🅢🅐 | + variant=button 按钮组形态(对齐 antd Radio + Radio.Button) | | switch | 开关 | Switch | 🅢🅐 | + loading / checkedChildren / unCheckedChildren(对齐 antd Switch) | | slider | 滑动输入 | Slider | 🅢🅐 | 原生支持双滑块 + antd marks 刻度(对齐 antd Slider) | | toggle | 切换按钮 | Toggle | 🅢 | Radix Toggle,工具栏图标级开关(antd 体系无) | | toggle-group | 切换按钮组 | ToggleGroup | 🅢 | type=single | multiple,与 RadioButton 互补(antd 体系无) | | segmented | 分段控制 | Segmented | 🅐 | iOS / macOS 风格紧凑互斥单选(对齐 antd Segmented v5.0+) |

3.4 日期 / 时间 / 颜色 / 评分 / 文件

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | -------------------------------------------- | -------- | ----------- | ---- | -------------------------------------------------------------------- | | calendar | 日历 | Calendar | 🅢🅐 | react-day-picker v9,单 / 多 / 范围(对齐 antd Calendar) | | date-picker | 日期选择 | DatePicker | 🅢🅐 | Calendar + Popover 复合(对齐 antd DatePicker + RangePicker) | | time-picker | 时间选择 | TimePicker | 🅐 | 原生 input[type=time],SSR safe(对齐 antd TimePicker) | | color-picker | 颜色选择 | ColorPicker | 🅐 | 原生 color + alpha + hex + 预设色板(对齐 antd ColorPicker v5.5+) | | rate | 评分 | Rate | 🅐 | 半星 / 清零 / 自定义图标(对齐 antd Rate) | | upload | 上传 | Upload | 🅐 | 点击 + 拖拽双模式,内置 accept / maxCount / maxSize(对齐 antd Upload) |

4. 数据展示 / Data Display(8 件)

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | ---------------------------------------- | -------- | ------------------------- | ---- | ---------------------------------------------------------------------- | | table | 基础表格 | Table | 🅢🅐 | 原生 HTML 元素薄包装(视觉骨架,无交互) | | data-table | 数据表 | DataTable | 🅢🅐 | TanStack Table + Table + SimplePagination(对齐 antd Table 完整) | | carousel | 轮播 | Carousel | 🅢🅐 | embla-carousel-react,单 / 多 / 循环 / 垂直(对齐 antd Carousel) | | statistic | 统计数值 | Statistic | 🅐 | KPI 展示 + 趋势 + 千分位 + 精度 + Timer(对齐 antd Statistic v5.25) | | tree | 树形控件 | Tree | 🅐 | 递归,可展开 / 选 / 勾选(级联 + 半选)(对齐 antd Tree) | | timeline | 时间轴 | Timeline | 🅐 | 3 种布局 + 5 种圆点色 + pending 进行中(对齐 antd Timeline) | | typography | 排版 | Title/Paragraph/Text/Link | 🅢🅐 | Prose 容器 + 子组件 + ellipsis/copyable/editable(对齐 antd Typography) | | transfer | 穿梭框 | Transfer | 🅐 | 双侧 List + 移动,targetKeys 单一真值(对齐 antd Transfer) |

5. 反馈与浮层 / Feedback & Overlay(16 件)

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | -------------------------------------------- | ---------- | --------------- | ---- | ------------------------------------------------------------------------------------------------------- | | alert | 警示条 | Alert | 🅢🅐 | + type / showIcon / closable / banner(对齐 antd Alert) | | dialog | 对话框 | Dialog | 🅢🅐 | Radix Dialog;Header / Footer / Title / Description(对齐 antd Modal) | | alert-dialog | 确认对话框 | AlertDialog | 🅢🅐 | Radix AlertDialog;阻塞式 Action + Cancel(对齐 antd Modal.confirm) | | popconfirm | 气泡确认 | Popconfirm | 🅐 | 轻量确认,onConfirm Promise 自动 loading(对齐 antd Popconfirm) | | popover | 浮层 | Popover | 🅢🅐 | + antd arrow(对齐 antd Popover) | | command | 命令面板 | Command | 🅢 | cmdk(Linear / Raycast 风格)过滤 + 键盘导航 + a11y;同时作为 Select / AutoComplete 同源下拉内核(ADR 0029) | | tooltip | 文字提示 | Tooltip | 🅢🅐 | + arrow / placement(side) + 一行 wrapper API(对齐 antd Tooltip) | | hover-card | 悬浮卡片 | HoverCard | 🅢 | hover 触发的富内容卡(@user 卡片 / 链接预览)(antd 体系无) | | sheet | 侧边面板 | Sheet | 🅢🅐 | Radix Dialog + side(对齐 antd Drawer top/right/left) | | drawer | 抽屉 | Drawer | 🅢 | vaul,iOS 风格底部可拖拽(对齐 antd Drawer placement=bottom 但加拖拽) | | sonner | 消息提示 | Toaster + toast | 🅢🅐 | sonner 包装;短文字 toast(对齐 antd message) | | notification | 通知卡片 | notification | 🅐 | sonner toast.custom 二次封装;title + description 卡片(对齐 antd Notification) | | result | 结果页 | Result | 🅐 | 整页级反馈(成功 / 失败 / 404 / 403 / 500)(对齐 antd Result) | | empty | 空状态 | Empty | 🅐 | 列表 / 表格 / 搜索为空时占位 + extra 行动按钮(对齐 antd Empty) | | tour | 漫游引导 | Tour | 🅐 | 多步骤 spotlight + 卡片 + 步进(对齐 antd Tour v5.0+) | | watermark | 水印 | Watermark | 🅐 | SVG 平铺水印(前端视觉,不作安全防护)(对齐 antd Watermark v5.1+) |

6. 导航 / Navigation(14 件)

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | -------------------------------------------------- | -------- | ---------------- | ---- | ------------------------------------------------------------------------------- | | tabs | 标签页 | Tabs | 🅢🅐 | Radix Tabs + antd type(line/card) + extra(对齐 antd Tabs) | | accordion | 折叠面板 | Accordion | 🅢🅐 | 单 / 多展开(对齐 antd Collapse 的 accordion 模式) | | collapsible | 单区折叠 | Collapsible | 🅢 | 单区域展开收起,Radix 薄包装(antd 体系无独立组件) | | breadcrumb | 面包屑 | Breadcrumb | 🅢🅐 | + separator / itemRender(asChild 配路由)(对齐 antd Breadcrumb) | | pagination | 分页 | SimplePagination | 🅢🅐 | shadcn primitives + 高阶 SimplePagination(对齐 antd Pagination) | | steps | 步骤条 | Steps | 🅐 | 多步流程,状态推导(wait/process/finish/error)(对齐 antd Steps) | | dropdown-menu | 下拉菜单 | DropdownMenu | 🅢🅐 | Radix 完整(Item/CheckboxItem/RadioItem/Sub/...)(对齐 antd Dropdown) | | context-menu | 右键菜单 | ContextMenu | 🅢 | 与 DropdownMenu 形态一致,触发为右键(antd 体系无) | | menubar | 菜单栏 | Menubar | 🅢 | 应用顶部菜单栏(macOS 风格)(antd 体系无) | | navigation-menu | 导航菜单 | NavigationMenu | 🅢 | 网站主导航(富 Content 面板)(antd 体系无独立组件) | | sidebar | 侧边栏 | Sidebar | 🅢🅐 | shadcn 复合(Provider + Sidebar + Menu + Trigger)(对齐 antd Layout.Sider + Menu) | | anchor | 锚点 | Anchor | 🅐 | 长文档侧边锚点,IntersectionObserver 自动高亮(对齐 antd Anchor) | | affix | 固钉 | Affix | 🅐 | 滚动吸顶 / 吸底,保留原占位(对齐 antd Affix) | | float-button | 悬浮按钮 | FloatButton | 🅐 | 悬浮按钮 + Group + BackTop(对齐 antd FloatButton v5.0,替代旧 BackTop) |

7. 应用壳 / Application Shell(2 件)

| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 | | ---------------------------------- | -------- | ------- | ---- | ------------------------------------------------------------------- | | app | 应用容器 | App | 🅐 | 根容器,挂全局 Toaster + dir / lang(不接管主题)(对齐 antd App v5.1+) | | command | 命令面板 | Command | 🅢 | cmdk(Linear / Raycast 风格),下拉同源内核(antd 体系无) |

功能重合分析

结论:8 处相邻 family 经审视均无可合并项 — 每对组件在语义、API 或运行时上彼此正交。 以下列出关键 family 与边界:

1. Loading 类(3 件)— Spinner / Skeleton / Progress

| 组件 | 何时用 | 互斥点 | | -------- | ----------------------------------------------------------- | ------------------------------------- | | Spinner | 时长未知、行内 / 占位旋转(请求中、按钮提交) | 不传达进度 | | Skeleton | 结构占位(段落 / 卡片 / 图片骨架),首屏加载时承接最终布局 | 不旋转,语义是"shape 占位"而非"动作中" | | Progress | 时长可知(百分比),线形 / 环形 | 数字驱动,不可空 |

不可合并:三种用户感知的 affordance 完全不同。

2. Toast / 通知类(2 件)— sonner / notification

| 组件 | 何时用 | 互斥点 | | --------------------------- | ----------------------------------------------------------- | --------------------------- | | toast() (来自 sonner) | 短文字反馈("已保存"/"网络异常重试中") — 对齐 antd message | 无标题,单行 | | notification.success(...) | 标题 + 描述 + 状态图标卡片 — 对齐 antd Notification | 多行结构,适合"操作完成详情" |

已共用 sonner runtime:Notification 内部就是 sonner.toast.custom,已经是同源,各自 entry 只是给消费方更清晰的 API surface — 实质代码无重复。

3. Modal / Overlay 阻塞类(6 件)— Dialog / AlertDialog / Popconfirm / Sheet / Drawer / Tour

| 组件 | 何时用 | 互斥点 | | ----------- | ------------------------------------------------- | ---------------------------- | | Dialog | 通用模态,自由内容 | 中性,需自填语义 | | AlertDialog | 不可逆 / 高风险 二次确认(注销 / 删库) | 强 Action + Cancel,无 X 关闭 | | Popconfirm | 低风险 行内 / 行末轻量确认(删一行 / 忽略一条) | 锚定触发器,不阻塞页面 | | Sheet | 侧边滑出,4 方向(antd Drawer placement) | 基于 Radix Dialog | | Drawer | 底部可拖拽(iOS 风格) | 基于 vaul,主打移动端 | | Tour | 多步引导(spotlight + 步进) | 时间性 + 跨步骤状态 |

Sheet ↔ Drawer 的边界值得详细说明(下文「合并建议」单列)。

4. 透明覆盖层(3 件)— Tooltip / Popover / HoverCard

| 组件 | 触发 | 内容 | 互斥点 | | --------- | ----------- | ----------------------------------- | ------------------------- | | Tooltip | hover(延迟) | 纯文本提示 | 不可交互 | | Popover | click | 可交互复合内容 | 通常带 trigger 按钮 | | HoverCard | hover(延迟) | 富 ReactNode(头像卡 / 链接预览) | 内容静态,可点击但不"激活" |

不可合并:触发方式 × 交互性 = 4 个象限,3 件覆盖 3 象限(剩 click + 纯文本 = AlertDialog)。

5. 选择类下拉(6 件)— Select / NativeSelect / AutoComplete / TreeSelect / Cascader / Segmented

| 组件 | value 域 | 候选呈现 | 互斥点 | | ------------ | ---------------------- | ----------------- | ------------------------- | | Select | options 之一 | Radix popup | 必选,无搜索 | | NativeSelect | options 之一 | 原生 picker | 0 JS,SSR / 移动端友好 | | AutoComplete | 任意字符串 | 自渲下拉 | 可自由输入,候选是建议 | | TreeSelect | options 之一(支持多选) | Tree 嵌入 Popover | 层级结构 | | Cascader | 路径数组 | 多列面板 | 级联,每层下钻 | | Segmented | options 之一 | inline 按钮组 | 2~5 档紧凑互斥 |

不可合并:value 形态 × 候选呈现 = 6 个独立场景。

6. 互斥单选可视化(4 件)— RadioGroup / Segmented / ToggleGroup(single)/ Tabs

| 组件 | 主场景 | 互斥点 | | ------------------- | ------------------------------------ | ---------------------- | | RadioGroup | 表单字段(性别 / 偏好) | 标准 radio 圆点 | | Segmented | 视图切换 / 时段档(日/周/月) | 紧凑分段,iOS 风格 | | ToggleGroup(single) | 工具栏图标按钮(B/I/U / 左/中/右) | 图标级,可切换 multiple | | Tabs | 页面 / 卡片内的切换 | 内容区域跟随切换 |

不可合并:视觉语义和上下文不同,虽然底层都是"互斥单选"。

7. 容器 / 卡片 / 空状态(4 件)— Card / Item / Empty / Result

| 组件 | 颗粒度 | 互斥点 | | ------ | ----------------------------------------------------- | ----------------------------- | | Card | 完整业务卡片(Header/Cover/Content/Footer/Actions) | 多 section | | Item | 列表 / 卡片单元行(Media + Content + Actions 5 槽) | 嵌入容器使用,取代旧 List.Item | | Empty | 空状态占位 | 含插画 + extra 行动按钮 | | Result | 整页级反馈(成功 / 失败 / 404 / 403 / 500) | 占据 viewport,含状态码与建议 |

不可合并:颗粒度从「单元 → 卡片 → 占位 → 整页」是清晰梯度。

8. 表单字段抽象(2 件)— Form / Field

| 组件 | 状态管理 | 互斥点 | | ------------------------------------ | --------------------------------------------------------------- | ---------------------- | | Form(FormField + FormItem + ...) | 强绑 react-hook-form + zod | 与 RHF schema 深度耦合 | | Field(FieldLabel + FieldError + ...) | 不绑 — 跟 Server Actions / TanStack Form / 原生 form 都能搭 | 仅 UI 抽象 |

不可合并:Form 是"RHF 流派的快速通道",Field 是"通用 UI 槽"。共存是有意为之。

合并建议

| 候选合并 | 建议 | 理由 | | ----------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Sheet ↔ Drawer | ❌ 保持分离 | Sheet 走 Radix Dialog(轻、4 方向、桌面端);Drawer 走 vaul(重、仅底部、可拖拽手势、iOS 风格)。两种不同的库 + 不同的 UX 范式,业务侧按场景选 | | Spinner ↔ Skeleton ↔ Progress | ❌ 保持分离 | 三种 affordance 互斥(见 §1) | | Tooltip ↔ Popover ↔ HoverCard | ❌ 保持分离 | 触发 × 交互性 4 象限(见 §4) | | Select ↔ AutoComplete | ❌ 保持分离 | value 域(必选 / 自由) × 是否搜索 = 4 类(见 §5) | | RadioGroup ↔ Segmented ↔ ToggleGroup ↔ Tabs | ❌ 保持分离 | 视觉语义不同(表单 / 视图切换 / 工具栏 / 页面切换) | | Form ↔ Field | ❌ 保持分离 | 状态管理绑定差异(见 §8) | | toast() ↔ notification | ✅ 已合并 runtime | 都基于 sonner;notification 是 sonner.toast.custom 的二次封装,已是同源不同表层 | | Pagination ↔ SimplePagination | ✅ 已合并 entry | 在同一 pagination entry 内导出 shadcn primitives + 高阶 SimplePagination | | Tree ↔ TreeSelect | ✅ 依赖关系已表达 | TreeSelect 在 registryDependencies 中声明 Tree,装 TreeSelect 时 Tree 会被连带装入(无重复源码) | | resizable ↔ Splitter(antd) | ✅ 已 alias | resizable description 已标 "等价 antd Splitter(v5.21+)" |

删除 / 替代记录

• ~~list~~ — antd v6 已 deprecated(2026-04 PR #54182),官方推荐用 Flex/Grid + Card。已从本库删除,通用列表项请用 Item + ItemGroup(shadcn 2025-10 新)
• ~~Card.Grid~~ — antd 老 Card 子组件,本库未实现;统一改用 Grid (Row/Col) 或 Tailwind grid
• ~~Dropdown.Button~~ — antd v6 已移除,改用 ButtonGroup + DropdownMenu 组合

暂不实现(待用户需求触发)

| 组件 | 来源 | 暂缓理由 | | ------------------ | -------------------- | ------------------------------------- | | QRCode | 🅐(antd v5.1+) | 需引入 qrcode.react 依赖,用户暂跳过 | | Direction Provider | 🅢(shadcn 2026-01 新) | RTL provider,无业务需求暂缓 | | BorderBeam | 🅐(antd v6.4 装饰类) | 装饰组件,优先级低 |