@teamix-evo/ui 0.1.1 → 0.2.0

package/src/components/auto-complete/auto-complete.meta.md

@@ -4,10 +4,11 @@ name: AutoComplete
 type: component
 category: form
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 自动补全
 ---
 
-# AutoComplete
+# AutoComplete 自动补全
 
 输入即建议 — antd 独有补足。**等价 antd `AutoComplete`**。键入触发候选下拉,可选可改;**最终 value 可以是任意字符串**(不强制为选项之一),与 `Combobox`(必选)互补。配 `onSearch` 实现异步建议。
 
@@ -23,33 +24,41 @@ package: "@teamix-evo/ui"
 - 多选 → `Select multiple`
 - @提及输入 → `Mentions`
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `options` | `AutoCompleteOption[]` | – | ✓ | 候选项(antd `options` 并集) — 通常由 onSearch 回调刷新。 |
-| `value` | `string` | – | – | 受控值。 |
-| `defaultValue` | `string` | – | – | uncontrolled 初值。 |
-| `onChange` | `(value: string) => void` | – | – | 值变化回调 — 用户键入 / 选中候选时触发。 |
-| `onSearch` | `(query: string) => void` | – | – | 用户输入时回调,用于刷新 `options`(异步建议)。 |
-| `onSelect` | `(value: string, option: AutoCompleteOption) => void` | – | – | 选中候选时回调。 |
-| `openOnFocus` | `boolean` | `false` | – | 是否在输入框聚焦但 query 为空时显示完整 `options`(antd `defaultActiveFirstOption` 行为的近似)。 |
-| `emptyText` | `string` | `"无匹配项"` | – | 无匹配时的提示文本。 |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 容器尺寸 — 透传 Input.size。 |
+
+| 名称           | 类型                                                  | 默认值       | 必填 | 说明                                                                                            |
+| -------------- | ----------------------------------------------------- | ------------ | ---- | ----------------------------------------------------------------------------------------------- |
+| `options`      | `AutoCompleteOption[]`                                | –            | ✓    | 候选项(antd `options` 并集) — 通常由 onSearch 回调刷新。                                        |
+| `value`        | `string`                                              | –            | –    | 受控值。                                                                                        |
+| `defaultValue` | `string`                                              | –            | –    | uncontrolled 初值。                                                                             |
+| `onChange`     | `(value: string) => void`                             | –            | –    | 值变化回调 — 用户键入 / 选中候选时触发。                                                        |
+| `onSearch`     | `(query: string) => void`                             | –            | –    | 用户输入时回调,用于刷新 `options`(异步建议)。                                                   |
+| `onSelect`     | `(value: string, option: AutoCompleteOption) => void` | –            | –    | 选中候选时回调。                                                                                |
+| `openOnFocus`  | `boolean`                                             | `false`      | –    | 是否在输入框聚焦但 query 为空时显示完整 `options`(antd `defaultActiveFirstOption` 行为的近似)。 |
+| `emptyText`    | `string`                                              | `"无匹配项"` | –    | 无匹配时的提示文本。                                                                            |
+| `size`         | `'sm' \| 'default' \| 'lg'`                           | `"default"`  | –    | 容器尺寸 — 透传 Input.size。                                                                    |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add auto-complete` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry   | 类型      | 描述                                                                                            |
+| ------- | --------- | ----------------------------------------------------------------------------------------------- |
+| `cn`    | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                              |
 | `input` | component | 文本输入 — shadcn 简洁基底 + antd prefix/suffix/clearable/showCount/addonBefore/addonAfter/size |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

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

@@ -10,7 +10,7 @@ const meta: Meta<typeof AutoComplete> = {
     docs: {
       description: {
         component:
-          '输入即建议 — 键入触发候选下拉,可选可改。最终 value 是自由文本,不强制为选项之一(与 Combobox 必选互补)。配 onSearch 实现异步建议。等价 antd `AutoComplete`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '输入即建议 — 键入触发候选下拉，可选可改。最终 value 是自由文本，不强制为选项之一（与 Combobox 必选互补）。配 onSearch 实现异步建议。等价 antd `AutoComplete`。',
       },
     },
   },
@@ -81,7 +81,9 @@ export const AsyncSearch: Story = {
         options={opts}
         onSearch={(q) => {
           window.setTimeout(() => {
-            setOpts(all.filter((v) => v.includes(q)).map((v) => ({ value: v })));
+            setOpts(
+              all.filter((v) => v.includes(q)).map((v) => ({ value: v })),
+            );
           }, 80);
         }}
         placeholder="搜索城市(模拟异步)..."

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

@@ -1,13 +1,14 @@
 ---
 id: avatar
 name: Avatar
+displayName: 头像
 type: component
 category: foundation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Avatar
+# Avatar 头像
 
 头像 — Radix Avatar(图片加载失败自动回退到 Fallback)+ antd Avatar 的 `size / shape / Avatar.Group` 并集。
 
@@ -27,10 +28,21 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `size` | `'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 尺寸(antd 并集:sm 32 / default 40 / lg 48 / xl 64)。 |
-| `shape` | `'circle' \| 'square'` | `"circle"` | – | 形状(antd 并集)。 |
+
+#### Avatar
+
+| 名称    | 类型                                | 默认值      | 必填 | 说明                                                 |
+| ------- | ----------------------------------- | ----------- | ---- | ---------------------------------------------------- |
+| `size`  | `'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | –    | 尺寸(antd 并集:sm 32 / default 40 / lg 48 / xl 64)。 |
+| `shape` | `'circle' \| 'square'`              | `"circle"`  | –    | 形状(antd 并集)。                                    |
+
+#### AvatarGroup
+
+| 名称   | 类型                                | 默认值 | 必填 | 说明                                               |
+| ------ | ----------------------------------- | ------ | ---- | -------------------------------------------------- |
+| `max`  | `number`                            | `3`    | –    | 显示前 N 个 Avatar,其余收为 `+N` 折叠气泡。        |
+| `size` | `'sm' \| 'default' \| 'lg' \| 'xl'` | –      | –    | Group 内所有 Avatar 共享的尺寸,会覆盖单个 Avatar。 |
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -38,13 +50,14 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add avatar` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -53,9 +66,8 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add @radix-ui/react-avatar@^1.1.0 class-variance-authority@^0.7.0
 ```
-<!-- auto:deps:end -->
 
-> 子组件:`AvatarImage`(图片源)/ `AvatarFallback`(加载失败 / 无图时的占位)/ `AvatarGroup`(多头像折叠组,带 `max` 与 `size`)。
+<!-- auto:deps:end -->
 
 ## AI 生成纪律
 

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

@@ -9,7 +9,7 @@ const meta: Meta<typeof Avatar> = {
     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、形状 circle/square、`AvatarGroup` 堆叠。Image / Fallback 通过命名子组件组合。',
       },
     },
   },

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

@@ -1,23 +1,24 @@
 ---
 id: badge
 name: Badge
+displayName: 徽标
 type: component
 category: foundation
 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
 
@@ -37,16 +38,18 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`badge.tsx`](./badge.tsx) 的 `BadgeProps` interface JSDoc。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'warning'` | `"default"` | – | 视觉风格;`default / secondary / destructive / outline` 来自 shadcn, `success / warning` 来自 antd 状态色补足。 |
-| `count` | `number` | – | – | 数字徽标内容。配合 `children` 时,数字气泡浮在右上角(包裹模式); 无 `children` 时,渲染为独立小气泡(standalone 模式)。 `0` 默认不显示,需配 `showZero`。 |
-| `overflowCount` | `number` | `99` | – | 数字超过此值时显示 `${overflowCount}+`。仅在有 `count` 时生效。 |
-| `showZero` | `boolean` | `false` | – | `true` 时即使 `count === 0` 也显示气泡。 |
-| `dot` | `boolean` | `false` | – | `true` 时渲染为纯红点(无文字)。配合 `children` 时浮在右上角。 `dot` 与 `count` 同时存在,`dot` 优先。 |
-| `status` | `BadgeStatus` | – | – | 状态点 + 文字(`<dot> <text>` 行内组合),用于"运行中 / 已停止"等状态描述。 必须与 `children` 互斥使用 — 这是 standalone 状态条形态。 |
-| `text` | `React.ReactNode` | – | – | 配合 `status` 使用,渲染在状态点右侧。无 `status` 时忽略。 |
-| `children` | `React.ReactNode` | – | – | 被包裹的元素(包裹模式)或徽标文本内容(standalone 文本模式)。 |
+
+| 名称            | 类型                                                                               | 默认值      | 必填 | 说明                                                                                                                                                 |
+| --------------- | ---------------------------------------------------------------------------------- | ----------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`       | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'warning'` | `"default"` | –    | 视觉风格;`default / secondary / destructive / outline` 来自 shadcn, `success / warning` 来自 antd 状态色补足。                                       |
+| `count`         | `number`                                                                           | –           | –    | 数字徽标内容。配合 `children` 时,数字气泡浮在右上角(包裹模式); 无 `children` 时,渲染为独立小气泡(standalone 模式)。 `0` 默认不显示,需配 `showZero`。 |
+| `overflowCount` | `number`                                                                           | `99`        | –    | 数字超过此值时显示 `${overflowCount}+`。仅在有 `count` 时生效。                                                                                      |
+| `showZero`      | `boolean`                                                                          | `false`     | –    | `true` 时即使 `count === 0` 也显示气泡。                                                                                                             |
+| `dot`           | `boolean`                                                                          | `false`     | –    | `true` 时渲染为纯红点(无文字)。配合 `children` 时浮在右上角。 `dot` 与 `count` 同时存在,`dot` 优先。                                                 |
+| `status`        | `BadgeStatus`                                                                      | –           | –    | 状态点 + 文字(`<dot> <text>` 行内组合),用于"运行中 / 已停止"等状态描述。 必须与 `children` 互斥使用 — 这是 standalone 状态条形态。                   |
+| `text`          | `React.ReactNode`                                                                  | –           | –    | 配合 `status` 使用,渲染在状态点右侧。无 `status` 时忽略。                                                                                            |
+| `children`      | `React.ReactNode`                                                                  | –           | –    | 被包裹的元素(包裹模式)或徽标文本内容(standalone 文本模式)。                                                                                          |
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -54,13 +57,14 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add badge` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -69,6 +73,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add class-variance-authority@^0.7.0
 ```
+
 <!-- auto:deps:end -->
 
 > 除上述 props 外,Badge 透传所有 `<span>` 原生属性(`onClick` / `aria-*` / `id` / ...)。

package/src/components/badge/badge.tsx

@@ -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 =
@@ -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,13 +1,14 @@
 ---
 id: breadcrumb
 name: Breadcrumb
+displayName: 面包屑
 type: component
 category: navigation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Breadcrumb
+# Breadcrumb 面包屑
 
 面包屑 — 纯组合组件 + antd `separator` 自定义并集。
 **与 antd Breadcrumb 的差异**:antd 用 `routes` 数组配置;本组件走 shadcn 的**组合式**(每项手写 `<BreadcrumbItem>`),配 React Router / Next.js Link 时更灵活。
@@ -29,9 +30,19 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `separator` | `React.ReactNode` | – | – | 自定义分隔符(antd `separator` 并集)。每个 `<BreadcrumbSeparator />` 默认渲染 `<ChevronRight />`, 通过设置 children 可全局覆盖。 |
+
+#### Breadcrumb
+
+| 名称        | 类型              | 默认值 | 必填 | 说明                                                                                                                            |
+| ----------- | ----------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `separator` | `React.ReactNode` | –      | –    | 自定义分隔符(antd `separator` 并集)。每个 `<BreadcrumbSeparator />` 默认渲染 `<ChevronRight />`, 通过设置 children 可全局覆盖。 |
+
+#### BreadcrumbLink
+
+| 名称      | 类型      | 默认值 | 必填 | 说明                                                       |
+| --------- | --------- | ------ | ---- | ---------------------------------------------------------- |
+| `asChild` | `boolean` | –      | –    | 用 Slot 渲染为子元素(常配合 React Router / Next.js Link)。 |
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -39,13 +50,14 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add breadcrumb` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -54,9 +66,8 @@ package: "@teamix-evo/ui"
 ```bash
 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`(省略,中间路径折叠用)。
+<!-- auto:deps:end -->
 
 ## AI 生成纪律
 

package/src/components/breadcrumb/breadcrumb.stories.tsx

@@ -14,6 +14,14 @@ const meta: Meta<typeof Breadcrumb> = {
   title: '导航 · Navigation/Breadcrumb',
   component: Breadcrumb,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '面包屑 — 纯组合组件 + antd separator 自定义并集。支持 asChild 配合 React Router / Next.js Link,支持长路径省略(Ellipsis)。',
+      },
+    },
+  },
 };
 
 export default meta;

package/src/components/button/button.meta.md

@@ -1,13 +1,14 @@
 ---
 id: button
 name: Button
+displayName: 按钮
 type: component
 category: foundation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Button
+# Button 按钮
 
 通用按钮 — 基于 shadcn/ui Button 二次封装,补齐 antd 的 `loading / icon / shape / block` 等开箱即用能力。
 按钮文本、aria 状态由消费方提供;视觉与可访问性由组件保障。
@@ -15,7 +16,7 @@ package: "@teamix-evo/ui"
 ## When to use
 
 - 表单提交、对话框确认、列表行操作等触发性交互
-- 需要明确反馈"按下→处理中→完成"过程的场景(用 `loading`)
+- 需要明确反馈"按下 → 处理中 → 完成"过程的场景(用 `loading`)
 - 需要纯图标按钮时(用 `size="icon"` + `shape="circle"` 组合)
 
 ## When NOT to use
@@ -29,17 +30,19 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`button.tsx`](./button.tsx) 的 `ButtonProps` interface JSDoc。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'dashed' \| 'ghost' \| 'link'` | `"default"` | – | 视觉风格,语义按 design token 走。 |
-| `size` | `'sm' \| 'default' \| 'lg' \| 'icon'` | `"default"` | – | 尺寸,`icon` 为正方形纯图标按钮。 |
-| `shape` | `'default' \| 'round' \| 'circle'` | `"default"` | – | 形状,`circle` 配 `size="icon"` 得圆形按钮。 |
-| `block` | `boolean` | `false` | – | `true` 时撑满父容器宽度。 |
-| `asChild` | `boolean` | `false` | – | 用 Radix Slot 模式渲染为子元素;此时 `loading` / `icon` 被忽略。 |
-| `loading` | `boolean` | `false` | – | 显示自旋 spinner,自动 disabled,保留视觉宽度。 |
-| `icon` | `React.ReactNode` | – | – | 前置 / 后置图标(来自 `lucide-react`)。loading 时被 spinner 替换。 |
-| `iconPosition` | `'start' \| 'end'` | `"start"` | – | 图标 / spinner 相对文本的位置。 |
-| `children` | `React.ReactNode` | – | – | 按钮文本 / 内容。 |
+
+| 名称           | 类型                                                                                      | 默认值      | 必填 | 说明                                                              |
+| -------------- | ----------------------------------------------------------------------------------------- | ----------- | ---- | ----------------------------------------------------------------- |
+| `variant`      | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'dashed' \| 'ghost' \| 'link'` | `"default"` | –    | 视觉风格,语义按 design token 走。                                 |
+| `size`         | `'sm' \| 'default' \| 'lg' \| 'icon'`                                                     | `"default"` | –    | 尺寸,`icon` 为正方形纯图标按钮。                                  |
+| `shape`        | `'default' \| 'round' \| 'circle'`                                                        | `"default"` | –    | 形状,`circle` 配 `size="icon"` 得圆形按钮。                       |
+| `block`        | `boolean`                                                                                 | `false`     | –    | `true` 时撑满父容器宽度。                                         |
+| `asChild`      | `boolean`                                                                                 | `false`     | –    | 用 Radix Slot 模式渲染为子元素;此时 `loading` / `icon` 被忽略。   |
+| `loading`      | `boolean`                                                                                 | `false`     | –    | 显示自旋 spinner,自动 disabled,保留视觉宽度。                     |
+| `icon`         | `React.ReactNode`                                                                         | –           | –    | 前置 / 后置图标(来自 `lucide-react`)。loading 时被 spinner 替换。 |
+| `iconPosition` | `'start' \| 'end'`                                                                        | `"start"`   | –    | 图标 / spinner 相对文本的位置。                                   |
+| `children`     | `React.ReactNode`                                                                         | –           | –    | 按钮文本 / 内容。                                                 |
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -47,13 +50,14 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add button` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -62,6 +66,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add @radix-ui/react-slot@^1.1.0 class-variance-authority@^0.7.0 lucide-react@^0.460.0
 ```
+
 <!-- auto:deps:end -->
 
 > 除上述声明的 props 外,Button 同时透传所有原生 `<button>` 属性(`onClick` / `type` / `aria-*` / ...);`asChild=true` 时透传至 Radix Slot 的子元素。

package/src/components/button/button.stories.tsx

@@ -25,7 +25,7 @@ const meta: Meta<typeof Button> = {
     docs: {
       description: {
         component:
-          '通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant)。className 走 OpenTrek semantic tokens,所有视觉来自 `@teamix-evo/design`,无 mock。',
+          '通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant)。支持 7 种视觉风格、4 种尺寸、3 种形状,`loading` 自动禁用并显示 spinner,`asChild` 可渲染为任意元素。',
       },
     },
   },

package/src/components/button/demo/as-child.tsx

@@ -0,0 +1,24 @@
+import { Button } from '@/components/ui/button';
+
+/**
+ * asChild：用 Radix Slot 渲染为子元素（如 `<a>` / 路由 Link）。
+ * 此时 `loading` / `icon` prop 会被忽略，因为底层不再是 `<button>`。
+ */
+export default function Demo() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button asChild variant="link">
+        <a href="/ui/components/button">查看文档</a>
+      </Button>
+      <Button asChild>
+        <a
+          href="https://github.com/teamix-evo/teamix-evo"
+          target="_blank"
+          rel="noreferrer"
+        >
+          GitHub 仓库
+        </a>
+      </Button>
+    </div>
+  );
+}

package/src/components/button/demo/basic.tsx

@@ -0,0 +1,8 @@
+import { Button } from '@/components/ui/button';
+
+/**
+ * 最简用法：默认 variant + 默认 size。
+ */
+export default function Demo() {
+  return <Button>提交</Button>;
+}

package/src/components/button/demo/block.tsx

@@ -0,0 +1,16 @@
+import { Button } from '@/components/ui/button';
+
+/**
+ * 块级按钮：撑满父容器宽度。
+ * 不要再额外加 `className="w-full"` 重复声明。
+ */
+export default function Demo() {
+  return (
+    <div className="flex w-80 flex-col gap-3">
+      <Button block>登录</Button>
+      <Button block variant="outline">
+        注册
+      </Button>
+    </div>
+  );
+}

package/src/components/button/demo/loading.tsx

@@ -0,0 +1,19 @@
+import { Button } from '@/components/ui/button';
+
+/**
+ * Loading 状态：自动 disabled，spinner 替换 icon 占位，按钮宽度保持。
+ * 写 `loading` 即可，不要额外加 `disabled`。
+ */
+export default function Demo() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button loading>提交中</Button>
+      <Button variant="secondary" loading>
+        加载
+      </Button>
+      <Button variant="destructive" loading>
+        删除中
+      </Button>
+    </div>
+  );
+}

package/src/components/button/demo/shapes.tsx

@@ -0,0 +1,18 @@
+import { X } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+
+/**
+ * 三种形状：default / round / circle。
+ * circle 必须配 `size="icon"`，否则视觉会扁圆变形。
+ */
+export default function Demo() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button>Default</Button>
+      <Button shape="round">Round</Button>
+      <Button shape="circle" size="icon" variant="ghost" aria-label="关闭">
+        <X />
+      </Button>
+    </div>
+  );
+}

package/src/components/button/demo/sizes.tsx

@@ -0,0 +1,19 @@
+import { Plus } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+
+/**
+ * 四种尺寸：sm / default / lg / icon。
+ * icon 为正方形纯图标按钮，配合 `size="icon"` 使用。
+ */
+export default function Demo() {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button size="sm">Small</Button>
+      <Button size="default">Default</Button>
+      <Button size="lg">Large</Button>
+      <Button size="icon" aria-label="Add">
+        <Plus />
+      </Button>
+    </div>
+  );
+}