@teamix-evo/ui 0.1.1 → 0.3.0

package/README.md

@@ -2,14 +2,14 @@
 
 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`](./AGENTS.md) (and [`CLAUDE.md`](./CLAUDE.md)) before adding or changing components. They lay out the design-philosophy references (`@teamix-evo/design`'s OpenTrek system), the AI compliance checklist, and the ui-side engineering constraints. New components MUST follow that guide.
+> **🤖 Working on this package?** Read [`AGENTS.md`](./AGENTS.md) (and [`CLAUDE.md`](./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/design`**: the dev server imports OpenTrek tokens directly from the design 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/design` 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)` in v4 mode or `hsl(var(--primary))` in v3 mode. Semantic token names (`primary`, `destructive`, `muted`, ...) align with shadcn — see `@teamix-evo/design` for the token layer.
+- **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 placeholder paths like `@/utils/cn`. The CLI rewrites these to user-configured aliases (e.g. `@/lib/utils`) 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).
 
@@ -53,11 +53,11 @@ packages/ui/
 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). On install the CLI drops it at `.teamix-evo/design/components/<id>.meta.md`, where the design package's ai-rules can read it.
+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 (89 entries · 88 components + 1 util)
+## Component Matrix (91 entries · 90 components + 1 util)
 
 > 2026-05-16 校准 `manifest.json`,覆盖 **shadcn 60 件 ∪ antd v6 60 件** 的高频与中频集。
 >
@@ -71,144 +71,144 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). On install
 
 零依赖或仅依赖 `cn`,被后续大量组件依赖。
 
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [cn](src/utils/cn.ts) | 类名合并工具 | cn | util | clsx + tailwind-merge,所有组件的 className 合并基础 |
-| [button](src/components/button/) | 按钮 | Button | 🅢🅐 | shadcn Button + antd `loading` / `icon` / `shape` / `block` / `dashed` variant |
-| [label](src/components/label/) | 表单标签 | Label | 🅢 | Radix Label,补 `required` / `disabled` 显式视觉(对齐 antd Form.Item label 部分) |
-| [badge](src/components/badge/) | 徽标 | Badge | 🅢🅐 | 四种形态:文本徽标 / 数字气泡 / 红点 / 状态点(对齐 antd Badge) |
-| [separator](src/components/separator/) | 分隔线 | Separator | 🅢🅐 | shadcn Separator + antd Divider 的 `dashed` / 中间装饰文本 |
-| [skeleton](src/components/skeleton/) | 骨架屏 | Skeleton | 🅢🅐 | shadcn pulse + antd Avatar/Image/Button/Input/Paragraph 子家族 |
-| [avatar](src/components/avatar/) | 头像 | Avatar | 🅢🅐 | Radix Avatar + antd `size` / `shape` / `Avatar.Group` |
-| [progress](src/components/progress/) | 进度条 | Progress | 🅢🅐 | 线形 + 配套 `ProgressCircle` 环形(对齐 antd Progress) |
-| [spinner](src/components/spinner/) | 加载指示器 | Spinner | 🅢🅐 | shadcn 2025-10 新增;4 档尺寸 + 4 档语义色(对齐 antd Spin 无遮罩版) |
-| [kbd](src/components/kbd/) | 键位 | Kbd | 🅢 | shadcn 2025-10 新增;`Kbd` + `KbdGroup` 标注快捷键(antd 体系无) |
-| [aspect-ratio](src/components/aspect-ratio/) | 等比容器 | AspectRatio | 🅢 | Radix AspectRatio,无 layout shift(antd 体系无) |
-| [image](src/components/image/) | 图片 | Image | 🅐 | 自动加载占位 + 失败占位 + 点击预览(对齐 antd Image) |
-| [tag](src/components/tag/) | 标签 | Tag | 🅐 | 关键词标签 + `closable` + 6 种语义色 + `CheckableTag(Group)`(对齐 antd Tag v6) |
-
-### 2. 布局与容器 / Layout & Container(9 件)
-
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [space](src/components/space/) | 间距 | Space | 🅐 | 子项间距 / 对齐 / 换行 / split(对齐 antd Space) |
-| [flex](src/components/flex/) | 弹性布局 | Flex | 🅐 | Tailwind flex 的语义封装,支持 `as` 语义标签(对齐 antd Flex v5.10+) |
-| [grid](src/components/grid/) | 栅格 | Grid (Row + Col) | 🅐 | 24 栅格,CSS Grid 实现(对齐 antd Row + Col) |
-| [masonry](src/components/masonry/) | 瀑布流 | Masonry | 🅐 | CSS column-count 0 JS 实现(对齐 antd Masonry v6.0) |
-| [scroll-area](src/components/scroll-area/) | 滚动容器 | ScrollArea | 🅢 | Radix ScrollArea,跨浏览器一致滚动条(antd 体系无) |
-| [resizable](src/components/resizable/) | 可拖拽分栏 | Resizable | 🅢🅐 | react-resizable-panels,VS Code / Figma 风格(对齐 antd Splitter v5.21+) |
-| [card](src/components/card/) | 卡片 | Card | 🅢🅐 | + `hoverable` / `loading` / `Cover` / `Actions` / `Meta` / `CardAction`(2026-04 shadcn 新增子组件) |
-| [item](src/components/item/) | 列表项 | Item | 🅢 | shadcn 2025-10 新增;5 槽 Media/Content/Title/Description/Actions + ItemGroup(替代旧 List.Item) |
-| [descriptions](src/components/descriptions/) | 描述列表 | Descriptions | 🅐 | 键值对详情,items 数组驱动,bordered / span(对齐 antd Descriptions) |
+| id                                           | 中文名       | 英文        | 来源 | 关键能力 / antd 对应                                                            |
+| -------------------------------------------- | ------------ | ----------- | ---- | ------------------------------------------------------------------------------- |
+| [cn](src/utils/cn.ts)                        | 类名合并工具 | cn          | util | clsx + tailwind-merge,所有组件的 className 合并基础                             |
+| [button](src/components/button/)             | 按钮         | Button      | 🅢🅐   | shadcn Button + antd `loading` / `icon` / `shape` / `block` / `dashed` variant  |
+| [label](src/components/label/)               | 表单标签     | Label       | 🅢    | Radix Label,补 `required` / `disabled` 显式视觉(对齐 antd Form.Item label 部分) |
+| [badge](src/components/badge/)               | 徽标         | Badge       | 🅢🅐   | 四种形态:文本徽标 / 数字气泡 / 红点 / 状态点(对齐 antd Badge)                   |
+| [separator](src/components/separator/)       | 分隔线       | Separator   | 🅢🅐   | shadcn Separator + antd Divider 的 `dashed` / 中间装饰文本                      |
+| [skeleton](src/components/skeleton/)         | 骨架屏       | Skeleton    | 🅢🅐   | shadcn pulse + antd Avatar/Image/Button/Input/Paragraph 子家族                  |
+| [avatar](src/components/avatar/)             | 头像         | Avatar      | 🅢🅐   | Radix Avatar + antd `size` / `shape` / `Avatar.Group`                           |
+| [progress](src/components/progress/)         | 进度条       | Progress    | 🅢🅐   | 线形 + 配套 `ProgressCircle` 环形(对齐 antd Progress)                           |
+| [spinner](src/components/spinner/)           | 加载指示器   | Spinner     | 🅢🅐   | shadcn 2025-10 新增;4 档尺寸 + 4 档语义色(对齐 antd Spin 无遮罩版)              |
+| [kbd](src/components/kbd/)                   | 键位         | Kbd         | 🅢    | shadcn 2025-10 新增;`Kbd` + `KbdGroup` 标注快捷键(antd 体系无)                  |
+| [aspect-ratio](src/components/aspect-ratio/) | 等比容器     | AspectRatio | 🅢    | Radix AspectRatio,无 layout shift(antd 体系无)                                  |
+| [image](src/components/image/)               | 图片         | Image       | 🅐    | 自动加载占位 + 失败占位 + 点击预览(对齐 antd Image)                             |
+| [tag](src/components/tag/)                   | 标签         | Tag         | 🅐    | 关键词标签 + `closable` + 6 种语义色 + `CheckableTag(Group)`(对齐 antd Tag v6)  |
+
+### 2. 布局与容器 / Layout & Container(8 件)
+
+| id                                           | 中文名     | 英文             | 来源 | 关键能力 / antd 对应                                                                                                           |
+| -------------------------------------------- | ---------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
+| [flex](src/components/flex/)                 | 弹性布局   | Flex             | 🅐    | Tailwind flex 语义封装,`as` 语义标签 + `inline` + `split`——一个原子覆盖布局容器与 inline 小集合(等价 antd Flex v5.10+ ∪ Space) |
+| [grid](src/components/grid/)                 | 栅格       | Grid (Row + Col) | 🅐    | 24 栅格,CSS Grid 实现(对齐 antd Row + Col)                                                                                     |
+| [masonry](src/components/masonry/)           | 瀑布流     | Masonry          | 🅐    | CSS column-count 0 JS 实现(对齐 antd Masonry v6.0)                                                                             |
+| [scroll-area](src/components/scroll-area/)   | 滚动容器   | ScrollArea       | 🅢    | Radix ScrollArea,跨浏览器一致滚动条(antd 体系无)                                                                               |
+| [resizable](src/components/resizable/)       | 可拖拽分栏 | Resizable        | 🅢🅐   | react-resizable-panels,VS Code / Figma 风格(对齐 antd Splitter v5.21+)                                                         |
+| [card](src/components/card/)                 | 卡片       | Card             | 🅢🅐   | + `hoverable` / `loading` / `Cover` / `Actions` / `Meta` / `CardAction`(2026-04 shadcn 新增子组件)                             |
+| [item](src/components/item/)                 | 列表项     | Item             | 🅢    | shadcn 2025-10 新增;5 槽 Media/Content/Title/Description/Actions + ItemGroup(替代旧 List.Item)                                 |
+| [descriptions](src/components/descriptions/) | 描述列表   | Descriptions     | 🅐    | 键值对详情,items 数组驱动,bordered / span(对齐 antd Descriptions)                                                              |
 
 ### 3. 表单与输入 / Form & Input(28 件)
 
 #### 3.1 表单组装
 
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [form](src/components/form/) | 表单 | Form | 🅢🅐 | react-hook-form + zod + shadcn 7 件套(对齐 antd Form) |
-| [field](src/components/field/) | 字段抽象 | Field | 🅢 | shadcn 2025-10 新增;7 槽,可搭任何状态管理(对齐 antd Form.Item 的解耦版) |
-| [input-group](src/components/input-group/) | 输入框组 | InputGroup | 🅢 | shadcn 2025-10 新增;复合插槽(对齐 antd Input 的 prefix/suffix/addon 集合) |
-| [button-group](src/components/button-group/) | 按钮组 | ButtonGroup | 🅢🅐 | shadcn 2025-10 新增;Split Button / Toolbar(对齐 antd Space.Compact v6) |
+| id                                           | 中文名   | 英文        | 来源 | 关键能力 / antd 对应                                                      |
+| -------------------------------------------- | -------- | ----------- | ---- | ------------------------------------------------------------------------- |
+| [form](src/components/form/)                 | 表单     | Form        | 🅢🅐   | react-hook-form + zod + shadcn 7 件套(对齐 antd Form)                     |
+| [field](src/components/field/)               | 字段抽象 | Field       | 🅢    | shadcn 2025-10 新增;7 槽,可搭任何状态管理(对齐 antd Form.Item 的解耦版)   |
+| [input-group](src/components/input-group/)   | 输入框组 | InputGroup  | 🅢    | shadcn 2025-10 新增;复合插槽(对齐 antd Input 的 prefix/suffix/addon 集合) |
+| [button-group](src/components/button-group/) | 按钮组   | ButtonGroup | 🅢🅐   | shadcn 2025-10 新增;Split Button / Toolbar(对齐 antd Space.Compact v6)    |
 
 #### 3.2 文本类输入
 
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [input](src/components/input/) | 输入框 | Input | 🅢🅐 | + `prefix` / `suffix` / `clearable` / `showCount` / `addonBefore/After`(对齐 antd Input) |
-| [textarea](src/components/textarea/) | 多行文本框 | Textarea | 🅢🅐 | + `autoSize` / `showCount`(对齐 antd Input.TextArea) |
-| [input-number](src/components/input-number/) | 数字输入框 | InputNumber | 🅐 | 步进 + min/max 夹紧 + precision + 千分位 + null 空状态(对齐 antd InputNumber) |
-| [input-otp](src/components/input-otp/) | 验证码输入 | InputOTP | 🅢🅐 | input-otp 库封装,登录 / 二步验证 / PIN(对齐 antd Input.OTP v5.21+) |
-| [mentions](src/components/mentions/) | @ 提及输入 | Mentions | 🅐 | Textarea + @ 触发候选下拉,异步 onSearch(对齐 antd Mentions) |
+| id                                           | 中文名     | 英文        | 来源 | 关键能力 / antd 对应                                                                                          |
+| -------------------------------------------- | ---------- | ----------- | ---- | ------------------------------------------------------------------------------------------------------------- |
+| [input](src/components/input/)               | 输入框     | Input       | 🅢🅐   | + `clearable` / `showCount` / `size` / `error` 四档内建(复合形态已拆出独立 `InputGroup`,对齐 antd Input 集合) |
+| [textarea](src/components/textarea/)         | 多行文本框 | Textarea    | 🅢🅐   | + `autoSize` / `showCount`(对齐 antd Input.TextArea)                                                          |
+| [input-number](src/components/input-number/) | 数字输入框 | InputNumber | 🅐    | 步进 + min/max 夹紧 + precision + 千分位 + null 空状态(对齐 antd InputNumber)                                 |
+| [input-otp](src/components/input-otp/)       | 验证码输入 | InputOTP    | 🅢🅐   | input-otp 库封装,登录 / 二步验证 / PIN(对齐 antd Input.OTP v5.21+)                                            |
+| [mentions](src/components/mentions/)         | @ 提及输入 | Mentions    | 🅐    | Textarea + @ 触发候选下拉,异步 onSearch(对齐 antd Mentions)                                                   |
 
 #### 3.3 选择类(下拉 / 单选 / 多选)
 
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [select](src/components/select/) | 选择器 | Select | 🅢🅐 | Radix Select(对齐 antd Select 单选) |
-| [native-select](src/components/native-select/) | 原生选择器 | NativeSelect | 🅢 | shadcn 2025-10 新增;原生 `<select>`,移动端 / SSR 友好(antd 体系无) |
-| [combobox](src/components/combobox/) | 可搜索选择器 | Combobox | 🅢 | Command + Popover,必选(value ∈ options)(对齐 antd Select showSearch) |
-| [auto-complete](src/components/auto-complete/) | 自动完成 | AutoComplete | 🅐 | 自由输入 + 候选建议(value 可任意 string)(对齐 antd AutoComplete) |
-| [cascader](src/components/cascader/) | 级联选择 | Cascader | 🅐 | 多级联动,叶子触发 / 中途可选(对齐 antd Cascader) |
-| [tree-select](src/components/tree-select/) | 树形选择 | TreeSelect | 🅐 | Tree 嵌入 Popover,单选 / 多选(对齐 antd TreeSelect) |
-| [checkbox](src/components/checkbox/) | 多选框 | Checkbox | 🅢🅐 | Radix 原生 indeterminate + Checkbox.Group(对齐 antd Checkbox) |
-| [radio-group](src/components/radio-group/) | 单选组 | RadioGroup | 🅢🅐 | + `variant=button` 按钮组形态(对齐 antd Radio + Radio.Button) |
-| [switch](src/components/switch/) | 开关 | Switch | 🅢🅐 | + `loading` / `checkedChildren` / `unCheckedChildren`(对齐 antd Switch) |
-| [slider](src/components/slider/) | 滑动输入 | Slider | 🅢🅐 | 原生支持双滑块 + antd marks 刻度(对齐 antd Slider) |
-| [toggle](src/components/toggle/) | 切换按钮 | Toggle | 🅢 | Radix Toggle,工具栏图标级开关(antd 体系无) |
-| [toggle-group](src/components/toggle-group/) | 切换按钮组 | ToggleGroup | 🅢 | type=single \| multiple,与 RadioButton 互补(antd 体系无) |
-| [segmented](src/components/segmented/) | 分段控制 | Segmented | 🅐 | iOS / macOS 风格紧凑互斥单选(对齐 antd Segmented v5.0+) |
+| id                                             | 中文名       | 英文         | 来源 | 关键能力 / antd 对应                                                    |
+| ---------------------------------------------- | ------------ | ------------ | ---- | ----------------------------------------------------------------------- |
+| [select](src/components/select/)               | 选择器       | Select       | 🅢🅐   | Radix Select(对齐 antd Select 单选)                                     |
+| [native-select](src/components/native-select/) | 原生选择器   | NativeSelect | 🅢    | shadcn 2025-10 新增;原生 `<select>`,移动端 / SSR 友好(antd 体系无)      |
+| [combobox](src/components/combobox/)           | 可搜索选择器 | Combobox     | 🅢    | Command + Popover,必选(value ∈ options)(对齐 antd Select showSearch)    |
+| [auto-complete](src/components/auto-complete/) | 自动完成     | AutoComplete | 🅐    | 自由输入 + 候选建议(value 可任意 string)(对齐 antd AutoComplete)        |
+| [cascader](src/components/cascader/)           | 级联选择     | Cascader     | 🅐    | 多级联动,叶子触发 / 中途可选(对齐 antd Cascader)                        |
+| [tree-select](src/components/tree-select/)     | 树形选择     | TreeSelect   | 🅐    | Tree 嵌入 Popover,单选 / 多选(对齐 antd TreeSelect)                     |
+| [checkbox](src/components/checkbox/)           | 多选框       | Checkbox     | 🅢🅐   | Radix 原生 indeterminate + Checkbox.Group(对齐 antd Checkbox)           |
+| [radio-group](src/components/radio-group/)     | 单选组       | RadioGroup   | 🅢🅐   | + `variant=button` 按钮组形态(对齐 antd Radio + Radio.Button)           |
+| [switch](src/components/switch/)               | 开关         | Switch       | 🅢🅐   | + `loading` / `checkedChildren` / `unCheckedChildren`(对齐 antd Switch) |
+| [slider](src/components/slider/)               | 滑动输入     | Slider       | 🅢🅐   | 原生支持双滑块 + antd marks 刻度(对齐 antd Slider)                      |
+| [toggle](src/components/toggle/)               | 切换按钮     | Toggle       | 🅢    | Radix Toggle,工具栏图标级开关(antd 体系无)                              |
+| [toggle-group](src/components/toggle-group/)   | 切换按钮组   | ToggleGroup  | 🅢    | type=single \| multiple,与 RadioButton 互补(antd 体系无)                |
+| [segmented](src/components/segmented/)         | 分段控制     | Segmented    | 🅐    | iOS / macOS 风格紧凑互斥单选(对齐 antd Segmented v5.0+)                 |
 
 #### 3.4 日期 / 时间 / 颜色 / 评分 / 文件
 
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [calendar](src/components/calendar/) | 日历 | Calendar | 🅢🅐 | react-day-picker v9,单 / 多 / 范围(对齐 antd Calendar) |
-| [date-picker](src/components/date-picker/) | 日期选择 | DatePicker | 🅢🅐 | Calendar + Popover 复合(对齐 antd DatePicker + RangePicker) |
-| [time-picker](src/components/time-picker/) | 时间选择 | TimePicker | 🅐 | 原生 input[type=time],SSR safe(对齐 antd TimePicker) |
-| [color-picker](src/components/color-picker/) | 颜色选择 | ColorPicker | 🅐 | 原生 color + alpha + hex + 预设色板(对齐 antd ColorPicker v5.5+) |
-| [rate](src/components/rate/) | 评分 | Rate | 🅐 | 半星 / 清零 / 自定义图标(对齐 antd Rate) |
-| [upload](src/components/upload/) | 上传 | Upload | 🅐 | 点击 + 拖拽双模式,内置 accept / maxCount / maxSize(对齐 antd Upload) |
+| id                                           | 中文名   | 英文        | 来源 | 关键能力 / antd 对应                                                 |
+| -------------------------------------------- | -------- | ----------- | ---- | -------------------------------------------------------------------- |
+| [calendar](src/components/calendar/)         | 日历     | Calendar    | 🅢🅐   | react-day-picker v9,单 / 多 / 范围(对齐 antd Calendar)               |
+| [date-picker](src/components/date-picker/)   | 日期选择 | DatePicker  | 🅢🅐   | Calendar + Popover 复合(对齐 antd DatePicker + RangePicker)          |
+| [time-picker](src/components/time-picker/)   | 时间选择 | TimePicker  | 🅐    | 原生 input[type=time],SSR safe(对齐 antd TimePicker)                 |
+| [color-picker](src/components/color-picker/) | 颜色选择 | ColorPicker | 🅐    | 原生 color + alpha + hex + 预设色板(对齐 antd ColorPicker v5.5+)     |
+| [rate](src/components/rate/)                 | 评分     | Rate        | 🅐    | 半星 / 清零 / 自定义图标(对齐 antd Rate)                             |
+| [upload](src/components/upload/)             | 上传     | Upload      | 🅐    | 点击 + 拖拽双模式,内置 accept / maxCount / maxSize(对齐 antd Upload) |
 
 ### 4. 数据展示 / Data Display(8 件)
 
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [table](src/components/table/) | 基础表格 | Table | 🅢🅐 | 原生 HTML 元素薄包装(视觉骨架,无交互) |
-| [data-table](src/components/data-table/) | 数据表 | DataTable | 🅢🅐 | TanStack Table + Table + SimplePagination(对齐 antd Table 完整) |
-| [carousel](src/components/carousel/) | 轮播 | Carousel | 🅢🅐 | embla-carousel-react,单 / 多 / 循环 / 垂直(对齐 antd Carousel) |
-| [statistic](src/components/statistic/) | 统计数值 | Statistic | 🅐 | KPI 展示 + 趋势 + 千分位 + 精度 + `Timer`(对齐 antd Statistic v5.25) |
-| [tree](src/components/tree/) | 树形控件 | Tree | 🅐 | 递归,可展开 / 选 / 勾选(级联 + 半选)(对齐 antd Tree) |
-| [timeline](src/components/timeline/) | 时间轴 | Timeline | 🅐 | 3 种布局 + 5 种圆点色 + pending 进行中(对齐 antd Timeline) |
-| [typography](src/components/typography/) | 排版 | Title/Paragraph/Text/Link | 🅢🅐 | Prose 容器 + 子组件 + ellipsis/copyable/editable(对齐 antd Typography) |
-| [transfer](src/components/transfer/) | 穿梭框 | Transfer | 🅐 | 双侧 List + 移动,targetKeys 单一真值(对齐 antd Transfer) |
-
-### 5. 反馈与浮层 / Feedback & Overlay(15 件)
-
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [alert](src/components/alert/) | 警示条 | Alert | 🅢🅐 | + `type` / `showIcon` / `closable` / `banner`(对齐 antd Alert) |
-| [dialog](src/components/dialog/) | 对话框 | Dialog | 🅢🅐 | Radix Dialog;Header / Footer / Title / Description(对齐 antd Modal) |
-| [alert-dialog](src/components/alert-dialog/) | 确认对话框 | AlertDialog | 🅢🅐 | Radix AlertDialog;阻塞式 Action + Cancel(对齐 antd Modal.confirm) |
-| [popconfirm](src/components/popconfirm/) | 气泡确认 | Popconfirm | 🅐 | 轻量确认,onConfirm Promise 自动 loading(对齐 antd Popconfirm) |
-| [popover](src/components/popover/) | 浮层 | Popover | 🅢🅐 | + antd `arrow`(对齐 antd Popover) |
-| [tooltip](src/components/tooltip/) | 文字提示 | Tooltip | 🅢🅐 | + `arrow` / `placement(side)` + 一行 wrapper API(对齐 antd Tooltip) |
-| [hover-card](src/components/hover-card/) | 悬浮卡片 | HoverCard | 🅢 | hover 触发的富内容卡(@user 卡片 / 链接预览)(antd 体系无) |
-| [sheet](src/components/sheet/) | 侧边面板 | Sheet | 🅢🅐 | Radix Dialog + side(对齐 antd Drawer top/right/left) |
-| [drawer](src/components/drawer/) | 抽屉 | Drawer | 🅢 | vaul,iOS 风格底部可拖拽(对齐 antd Drawer placement=bottom 但加拖拽) |
-| [sonner](src/components/sonner/) | 消息提示 | Toaster + toast | 🅢🅐 | sonner 包装;短文字 toast(对齐 antd message) |
-| [notification](src/components/notification/) | 通知卡片 | notification | 🅐 | sonner toast.custom 二次封装;title + description 卡片(对齐 antd Notification) |
-| [result](src/components/result/) | 结果页 | Result | 🅐 | 整页级反馈(成功 / 失败 / 404 / 403 / 500)(对齐 antd Result) |
-| [empty](src/components/empty/) | 空状态 | Empty | 🅐 | 列表 / 表格 / 搜索为空时占位 + extra 行动按钮(对齐 antd Empty) |
-| [tour](src/components/tour/) | 漫游引导 | Tour | 🅐 | 多步骤 spotlight + 卡片 + 步进(对齐 antd Tour v5.0+) |
-| [watermark](src/components/watermark/) | 水印 | Watermark | 🅐 | SVG 平铺水印(前端视觉,不作安全防护)(对齐 antd Watermark v5.1+) |
+| id                                       | 中文名   | 英文                      | 来源 | 关键能力 / antd 对应                                                   |
+| ---------------------------------------- | -------- | ------------------------- | ---- | ---------------------------------------------------------------------- |
+| [table](src/components/table/)           | 基础表格 | Table                     | 🅢🅐   | 原生 HTML 元素薄包装(视觉骨架,无交互)                                  |
+| [data-table](src/components/data-table/) | 数据表   | DataTable                 | 🅢🅐   | TanStack Table + Table + SimplePagination(对齐 antd Table 完整)        |
+| [carousel](src/components/carousel/)     | 轮播     | Carousel                  | 🅢🅐   | embla-carousel-react,单 / 多 / 循环 / 垂直(对齐 antd Carousel)         |
+| [statistic](src/components/statistic/)   | 统计数值 | Statistic                 | 🅐    | KPI 展示 + 趋势 + 千分位 + 精度 + `Timer`(对齐 antd Statistic v5.25)   |
+| [tree](src/components/tree/)             | 树形控件 | Tree                      | 🅐    | 递归,可展开 / 选 / 勾选(级联 + 半选)(对齐 antd Tree)                   |
+| [timeline](src/components/timeline/)     | 时间轴   | Timeline                  | 🅐    | 3 种布局 + 5 种圆点色 + pending 进行中(对齐 antd Timeline)             |
+| [typography](src/components/typography/) | 排版     | Title/Paragraph/Text/Link | 🅢🅐   | Prose 容器 + 子组件 + ellipsis/copyable/editable(对齐 antd Typography) |
+| [transfer](src/components/transfer/)     | 穿梭框   | Transfer                  | 🅐    | 双侧 List + 移动,targetKeys 单一真值(对齐 antd Transfer)               |
+
+### 5. 反馈与浮层 / Feedback & Overlay(16 件)
+
+| id                                           | 中文名     | 英文            | 来源 | 关键能力 / antd 对应                                                                                               |
+| -------------------------------------------- | ---------- | --------------- | ---- | ------------------------------------------------------------------------------------------------------------------ |
+| [alert](src/components/alert/)               | 警示条     | Alert           | 🅢🅐   | + `type` / `showIcon` / `closable` / `banner`(对齐 antd Alert)                                                     |
+| [dialog](src/components/dialog/)             | 对话框     | Dialog          | 🅢🅐   | Radix Dialog;Header / Footer / Title / Description(对齐 antd Modal)                                                |
+| [alert-dialog](src/components/alert-dialog/) | 确认对话框 | AlertDialog     | 🅢🅐   | Radix AlertDialog;阻塞式 Action + Cancel(对齐 antd Modal.confirm)                                                  |
+| [popconfirm](src/components/popconfirm/)     | 气泡确认   | Popconfirm      | 🅐    | 轻量确认,onConfirm Promise 自动 loading(对齐 antd Popconfirm)                                                      |
+| [popover](src/components/popover/)           | 浮层       | Popover         | 🅢🅐   | + antd `arrow`(对齐 antd Popover)                                                                                  |
+| [command](src/components/command/)           | 命令面板   | Command         | 🅢    | cmdk(Linear / Raycast 风格)过滤 + 键盘导航 + a11y;同时作为 Combobox / Select / AutoComplete 同源下拉内核(ADR 0029) |
+| [tooltip](src/components/tooltip/)           | 文字提示   | Tooltip         | 🅢🅐   | + `arrow` / `placement(side)` + 一行 wrapper API(对齐 antd Tooltip)                                                |
+| [hover-card](src/components/hover-card/)     | 悬浮卡片   | HoverCard       | 🅢    | hover 触发的富内容卡(@user 卡片 / 链接预览)(antd 体系无)                                                           |
+| [sheet](src/components/sheet/)               | 侧边面板   | Sheet           | 🅢🅐   | Radix Dialog + side(对齐 antd Drawer top/right/left)                                                               |
+| [drawer](src/components/drawer/)             | 抽屉       | Drawer          | 🅢    | vaul,iOS 风格底部可拖拽(对齐 antd Drawer placement=bottom 但加拖拽)                                                |
+| [sonner](src/components/sonner/)             | 消息提示   | Toaster + toast | 🅢🅐   | sonner 包装;短文字 toast(对齐 antd message)                                                                        |
+| [notification](src/components/notification/) | 通知卡片   | notification    | 🅐    | sonner toast.custom 二次封装;title + description 卡片(对齐 antd Notification)                                      |
+| [result](src/components/result/)             | 结果页     | Result          | 🅐    | 整页级反馈(成功 / 失败 / 404 / 403 / 500)(对齐 antd Result)                                                        |
+| [empty](src/components/empty/)               | 空状态     | Empty           | 🅐    | 列表 / 表格 / 搜索为空时占位 + extra 行动按钮(对齐 antd Empty)                                                     |
+| [tour](src/components/tour/)                 | 漫游引导   | Tour            | 🅐    | 多步骤 spotlight + 卡片 + 步进(对齐 antd Tour v5.0+)                                                               |
+| [watermark](src/components/watermark/)       | 水印       | Watermark       | 🅐    | SVG 平铺水印(前端视觉,不作安全防护)(对齐 antd Watermark v5.1+)                                                     |
 
 ### 6. 导航 / Navigation(14 件)
 
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [tabs](src/components/tabs/) | 标签页 | Tabs | 🅢🅐 | Radix Tabs + antd `type(line/card)` + extra(对齐 antd Tabs) |
-| [accordion](src/components/accordion/) | 折叠面板 | Accordion | 🅢🅐 | 单 / 多展开(对齐 antd Collapse 的 accordion 模式) |
-| [collapsible](src/components/collapsible/) | 单区折叠 | Collapsible | 🅢 | 单区域展开收起,Radix 薄包装(antd 体系无独立组件) |
-| [breadcrumb](src/components/breadcrumb/) | 面包屑 | Breadcrumb | 🅢🅐 | + `separator` / `itemRender`(asChild 配路由)(对齐 antd Breadcrumb) |
-| [pagination](src/components/pagination/) | 分页 | SimplePagination | 🅢🅐 | shadcn primitives + 高阶 SimplePagination(对齐 antd Pagination) |
-| [steps](src/components/steps/) | 步骤条 | Steps | 🅐 | 多步流程,状态推导(wait/process/finish/error)(对齐 antd Steps) |
-| [dropdown-menu](src/components/dropdown-menu/) | 下拉菜单 | DropdownMenu | 🅢🅐 | Radix 完整(Item/CheckboxItem/RadioItem/Sub/...)(对齐 antd Dropdown) |
-| [context-menu](src/components/context-menu/) | 右键菜单 | ContextMenu | 🅢 | 与 DropdownMenu 形态一致,触发为右键(antd 体系无) |
-| [menubar](src/components/menubar/) | 菜单栏 | Menubar | 🅢 | 应用顶部菜单栏(macOS 风格)(antd 体系无) |
-| [navigation-menu](src/components/navigation-menu/) | 导航菜单 | NavigationMenu | 🅢 | 网站主导航(富 Content 面板)(antd 体系无独立组件) |
-| [sidebar](src/components/sidebar/) | 侧边栏 | Sidebar | 🅢🅐 | shadcn 复合(Provider + Sidebar + Menu + Trigger)(对齐 antd Layout.Sider + Menu) |
-| [anchor](src/components/anchor/) | 锚点 | Anchor | 🅐 | 长文档侧边锚点,IntersectionObserver 自动高亮(对齐 antd Anchor) |
-| [affix](src/components/affix/) | 固钉 | Affix | 🅐 | 滚动吸顶 / 吸底,保留原占位(对齐 antd Affix) |
-| [float-button](src/components/float-button/) | 悬浮按钮 | FloatButton | 🅐 | 悬浮按钮 + Group + BackTop(对齐 antd FloatButton v5.0,替代旧 BackTop) |
+| id                                                 | 中文名   | 英文             | 来源 | 关键能力 / antd 对应                                                            |
+| -------------------------------------------------- | -------- | ---------------- | ---- | ------------------------------------------------------------------------------- |
+| [tabs](src/components/tabs/)                       | 标签页   | Tabs             | 🅢🅐   | Radix Tabs + antd `type(line/card)` + extra(对齐 antd Tabs)                     |
+| [accordion](src/components/accordion/)             | 折叠面板 | Accordion        | 🅢🅐   | 单 / 多展开(对齐 antd Collapse 的 accordion 模式)                               |
+| [collapsible](src/components/collapsible/)         | 单区折叠 | Collapsible      | 🅢    | 单区域展开收起,Radix 薄包装(antd 体系无独立组件)                                |
+| [breadcrumb](src/components/breadcrumb/)           | 面包屑   | Breadcrumb       | 🅢🅐   | + `separator` / `itemRender`(asChild 配路由)(对齐 antd Breadcrumb)              |
+| [pagination](src/components/pagination/)           | 分页     | SimplePagination | 🅢🅐   | shadcn primitives + 高阶 SimplePagination(对齐 antd Pagination)                 |
+| [steps](src/components/steps/)                     | 步骤条   | Steps            | 🅐    | 多步流程,状态推导(wait/process/finish/error)(对齐 antd Steps)                   |
+| [dropdown-menu](src/components/dropdown-menu/)     | 下拉菜单 | DropdownMenu     | 🅢🅐   | Radix 完整(Item/CheckboxItem/RadioItem/Sub/...)(对齐 antd Dropdown)             |
+| [context-menu](src/components/context-menu/)       | 右键菜单 | ContextMenu      | 🅢    | 与 DropdownMenu 形态一致,触发为右键(antd 体系无)                                |
+| [menubar](src/components/menubar/)                 | 菜单栏   | Menubar          | 🅢    | 应用顶部菜单栏(macOS 风格)(antd 体系无)                                         |
+| [navigation-menu](src/components/navigation-menu/) | 导航菜单 | NavigationMenu   | 🅢    | 网站主导航(富 Content 面板)(antd 体系无独立组件)                                |
+| [sidebar](src/components/sidebar/)                 | 侧边栏   | Sidebar          | 🅢🅐   | shadcn 复合(Provider + Sidebar + Menu + Trigger)(对齐 antd Layout.Sider + Menu) |
+| [anchor](src/components/anchor/)                   | 锚点     | Anchor           | 🅐    | 长文档侧边锚点,IntersectionObserver 自动高亮(对齐 antd Anchor)                  |
+| [affix](src/components/affix/)                     | 固钉     | Affix            | 🅐    | 滚动吸顶 / 吸底,保留原占位(对齐 antd Affix)                                     |
+| [float-button](src/components/float-button/)       | 悬浮按钮 | FloatButton      | 🅐    | 悬浮按钮 + Group + BackTop(对齐 antd FloatButton v5.0,替代旧 BackTop)           |
 
 ### 7. 应用壳 / Application Shell(2 件)
 
-| id | 中文名 | 英文 | 来源 | 关键能力 / antd 对应 |
-| --- | --- | --- | --- | --- |
-| [app](src/components/app/) | 应用容器 | App | 🅐 | 根容器,挂全局 Toaster + dir / lang(不接管主题)(对齐 antd App v5.1+) |
-| [command](src/components/command/) | 命令面板 | Command | 🅢 | cmdk(Linear / Raycast 风格),Combobox 的底座(antd 体系无) |
+| id                                 | 中文名   | 英文    | 来源 | 关键能力 / antd 对应                                                |
+| ---------------------------------- | -------- | ------- | ---- | ------------------------------------------------------------------- |
+| [app](src/components/app/)         | 应用容器 | App     | 🅐    | 根容器,挂全局 Toaster + dir / lang(不接管主题)(对齐 antd App v5.1+) |
+| [command](src/components/command/) | 命令面板 | Command | 🅢    | cmdk(Linear / Raycast 风格),Combobox 的底座(antd 体系无)            |
 
 ---
 
@@ -218,88 +218,88 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). On install
 
 ### 1. Loading 类(3 件)— Spinner / Skeleton / Progress
 
-| 组件 | 何时用 | 互斥点 |
-| --- | --- | --- |
-| Spinner | 时长未知、行内 / 占位旋转(请求中、按钮提交) | 不传达进度 |
+| 组件     | 何时用                                                      | 互斥点                                |
+| -------- | ----------------------------------------------------------- | ------------------------------------- |
+| Spinner  | 时长未知、行内 / 占位旋转(请求中、按钮提交)                 | 不传达进度                            |
 | Skeleton | **结构占位**(段落 / 卡片 / 图片骨架),首屏加载时承接最终布局 | 不旋转,语义是"shape 占位"而非"动作中" |
-| Progress | 时长可知(百分比),线形 / 环形 | 数字驱动,不可空 |
+| Progress | 时长可知(百分比),线形 / 环形                                | 数字驱动,不可空                       |
 
 **不可合并**:三种用户感知的 affordance 完全不同。
 
 ### 2. Toast / 通知类(2 件)— sonner / notification
 
-| 组件 | 何时用 | 互斥点 |
-| --- | --- | --- |
-| `toast()` (来自 sonner) | 短文字反馈("已保存"/"网络异常重试中") — 对齐 antd `message` | 无标题,单行 |
-| `notification.success(...)` | 标题 + 描述 + 状态图标卡片 — 对齐 antd `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 + 步进) | 时间性 + 跨步骤状态 |
+| 组件        | 何时用                                            | 互斥点                       |
+| ----------- | ------------------------------------------------- | ---------------------------- |
+| 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 按钮 |
+| 组件      | 触发        | 内容                                | 互斥点                    |
+| --------- | ----------- | ----------------------------------- | ------------------------- |
+| Tooltip   | hover(延迟) | **纯文本提示**                      | 不可交互                  |
+| Popover   | **click**   | **可交互复合内容**                  | 通常带 trigger 按钮       |
 | HoverCard | hover(延迟) | **富 ReactNode**(头像卡 / 链接预览) | 内容静态,可点击但不"激活" |
 
-**不可合并**:触发方式 ×  交互性 = 4 个象限,3 件覆盖 3 象限(剩 click + 纯文本 = AlertDialog)。
+**不可合并**:触发方式 × 交互性 = 4 个象限,3 件覆盖 3 象限(剩 click + 纯文本 = AlertDialog)。
 
 ### 5. 选择类下拉(7 件)— Select / NativeSelect / Combobox / AutoComplete / TreeSelect / Cascader / Segmented
 
-| 组件 | value 域 | 候选呈现 | 互斥点 |
-| --- | --- | --- | --- |
-| Select | options 之一 | Radix popup | **必选**,无搜索 |
-| NativeSelect | options 之一 | 原生 picker | **0 JS**,SSR / 移动端友好 |
-| Combobox | options 之一 | Command + Popover | **必选 + 搜索** |
-| AutoComplete | **任意字符串** | 自渲下拉 | **可自由输入**,候选是建议 |
-| TreeSelect | options 之一(支持多选) | Tree 嵌入 Popover | **层级结构** |
-| Cascader | 路径数组 | 多列面板 | **级联,每层下钻** |
-| Segmented | options 之一 | inline 按钮组 | **2~5 档紧凑互斥** |
+| 组件         | value 域               | 候选呈现          | 互斥点                    |
+| ------------ | ---------------------- | ----------------- | ------------------------- |
+| Select       | options 之一           | Radix popup       | **必选**,无搜索           |
+| NativeSelect | options 之一           | 原生 picker       | **0 JS**,SSR / 移动端友好 |
+| Combobox     | options 之一           | Command + Popover | **必选 + 搜索**           |
+| AutoComplete | **任意字符串**         | 自渲下拉          | **可自由输入**,候选是建议 |
+| TreeSelect   | options 之一(支持多选) | Tree 嵌入 Popover | **层级结构**              |
+| Cascader     | 路径数组               | 多列面板          | **级联,每层下钻**         |
+| Segmented    | options 之一           | inline 按钮组     | **2~5 档紧凑互斥**        |
 
 **不可合并**:value 形态 × 候选呈现 = 7 个独立场景。
 
 ### 6. 互斥单选可视化(4 件)— RadioGroup / Segmented / ToggleGroup(single)/ Tabs
 
-| 组件 | 主场景 | 互斥点 |
-| --- | --- | --- |
-| RadioGroup | **表单字段**(性别 / 偏好) | 标准 radio 圆点 |
-| Segmented | **视图切换 / 时段档**(日/周/月) | 紧凑分段,iOS 风格 |
+| 组件                | 主场景                               | 互斥点                 |
+| ------------------- | ------------------------------------ | ---------------------- |
+| RadioGroup          | **表单字段**(性别 / 偏好)            | 标准 radio 圆点        |
+| Segmented           | **视图切换 / 时段档**(日/周/月)      | 紧凑分段,iOS 风格      |
 | ToggleGroup(single) | **工具栏图标按钮**(B/I/U / 左/中/右) | 图标级,可切换 multiple |
-| Tabs | **页面 / 卡片内的切换** | 内容区域跟随切换 |
+| 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,含状态码与建议 |
+| 组件   | 颗粒度                                                | 互斥点                        |
+| ------ | ----------------------------------------------------- | ----------------------------- |
+| 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(FormField + FormItem + ...)     | **强绑 react-hook-form + zod**                                  | 与 RHF schema 深度耦合 |
+| Field(FieldLabel + FieldError + ...) | **不绑** — 跟 Server Actions / TanStack Form / 原生 form 都能搭 | 仅 UI 抽象             |
 
 **不可合并**:Form 是"RHF 流派的快速通道",Field 是"通用 UI 槽"。共存是有意为之。
 
@@ -307,18 +307,18 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). On install
 
 ## 合并建议
 
-| 候选合并 | 建议 | 理由 |
-| --- | --- | --- |
-| **Sheet ↔ Drawer** | ❌ **保持分离** | Sheet 走 Radix Dialog(轻、4 方向、桌面端);Drawer 走 vaul(重、仅底部、可拖拽手势、iOS 风格)。**两种不同的库 + 不同的 UX 范式**,业务侧按场景选 |
-| **Spinner ↔ Skeleton ↔ Progress** | ❌ **保持分离** | 三种 affordance 互斥(见 §1) |
-| **Tooltip ↔ Popover ↔ HoverCard** | ❌ **保持分离** | 触发 × 交互性 4 象限(见 §4) |
-| **Select ↔ Combobox ↔ 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+)" |
+| 候选合并                                        | 建议                  | 理由                                                                                                                                         |
+| ----------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Sheet ↔ Drawer**                              | ❌ **保持分离**       | Sheet 走 Radix Dialog(轻、4 方向、桌面端);Drawer 走 vaul(重、仅底部、可拖拽手势、iOS 风格)。**两种不同的库 + 不同的 UX 范式**,业务侧按场景选 |
+| **Spinner ↔ Skeleton ↔ Progress**               | ❌ **保持分离**       | 三种 affordance 互斥(见 §1)                                                                                                                  |
+| **Tooltip ↔ Popover ↔ HoverCard**               | ❌ **保持分离**       | 触发 × 交互性 4 象限(见 §4)                                                                                                                  |
+| **Select ↔ Combobox ↔ 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+)"                                                                                    |
 
 ### 删除 / 替代记录
 
@@ -328,9 +328,9 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). On install
 
 ### 暂不实现(待用户需求触发)
 
-| 组件 | 来源 | 暂缓理由 |
-| --- | --- | --- |
-| Chart | 🅢🅐(shadcn 2026-03 升 Recharts v3 / antd Plot) | 用户指示暂跳过 |
-| QRCode | 🅐(antd v5.1+) | 需引入 `qrcode.react` 依赖,用户暂跳过 |
-| Direction Provider | 🅢(shadcn 2026-01 新) | RTL provider,无业务需求暂缓 |
-| BorderBeam | 🅐(antd v6.4 装饰类) | 装饰组件,优先级低 |
+| 组件               | 来源                                          | 暂缓理由                              |
+| ------------------ | --------------------------------------------- | ------------------------------------- |
+| Chart              | 🅢🅐(shadcn 2026-03 升 Recharts v3 / antd Plot) | 用户指示暂跳过                        |
+| QRCode             | 🅐(antd v5.1+)                                 | 需引入 `qrcode.react` 依赖,用户暂跳过 |
+| Direction Provider | 🅢(shadcn 2026-01 新)                          | RTL provider,无业务需求暂缓           |
+| BorderBeam         | 🅐(antd v6.4 装饰类)                           | 装饰组件,优先级低                     |