@teamix-evo/ui 0.1.1 → 0.2.0

package/src/components/spinner/spinner.meta.md

@@ -1,13 +1,14 @@
 ---
 id: spinner
 name: Spinner
+displayName: 加载指示器
 type: component
 category: foundation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Spinner
+# Spinner 加载指示器
 
 旋转加载指示器 — shadcn 2025-10 新增,**等价 antd `Spin`**(无遮罩版)。基于 `lucide-react` 的 `Loader2`,4 档尺寸 + 4 档语义配色,自带 `role="status"` 与读屏文本。
 
@@ -23,22 +24,33 @@ package: "@teamix-evo/ui"
 - 整页"模态阻塞 loading" → `Dialog` + Spinner 自行组合(本组件不内置遮罩)
 - 进度可知场景 → `Progress`(线形)或 `ProgressCircle`(环形)
 
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `size` | `'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 尺寸 — 与 antd Spin 的 small/middle/large 对齐(加 xl 用于全屏 loading)。 |
-| `tone` | `'default' \| 'muted' \| 'primary' \| 'destructive'` | `"default"` | – | 配色 — `muted` 走次级文本色;`primary` / `destructive` 走语义色。 |
-| `label` | `string` | – | – | 给读屏器的描述(默认 "Loading...")。 |
+
+| 名称    | 类型                                                 | 默认值      | 必填 | 说明                                                                     |
+| ------- | ---------------------------------------------------- | ----------- | ---- | ------------------------------------------------------------------------ |
+| `size`  | `'sm' \| 'default' \| 'lg' \| 'xl'`                  | `"default"` | –    | 尺寸 — 与 antd Spin 的 small/middle/large 对齐(加 xl 用于全屏 loading)。 |
+| `tone`  | `'default' \| 'muted' \| 'primary' \| 'destructive'` | `"default"` | –    | 配色 — `muted` 走次级文本色;`primary` / `destructive` 走语义色。         |
+| `label` | `string`                                             | –           | –    | 给读屏器的描述(默认 "Loading...")。                                      |
+
 <!-- auto:props:end -->
 
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成，数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add spinner` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -47,6 +59,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add class-variance-authority@^0.7.0 lucide-react@^0.460.0
 ```
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/spinner/spinner.stories.tsx

@@ -9,7 +9,7 @@ const meta: Meta<typeof Spinner> = {
     docs: {
       description: {
         component:
-          '旋转加载指示器 — 局部 / 行内 loading(请求中、按钮提交、占位等待)。基于 lucide Loader2,4 档尺寸 + 4 档配色,自带 role="status" 与 sr-only 读屏文案。shadcn 2025-10 新增,对齐 antd `Spin`(无遮罩版本)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '旋转加载指示器 — 局部 / 行内 loading（请求中、按钮提交、占位等待）。基于 lucide Loader2，4 档尺寸 + 4 档配色，自带 role="status" 与 sr-only 读屏文案。对齐 antd `Spin`（无遮罩版本）。',
       },
     },
   },

package/src/components/statistic/statistic.meta.md

@@ -1,13 +1,14 @@
 ---
 id: statistic
 name: Statistic
+displayName: 统计数值
 type: component
 category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Statistic
+# Statistic 统计数值
 
 数字展示 — antd 独有补足。**仪表板专用**:大字号数值 + 标题 + 前缀(¥/$ / 图标)+ 后缀(单位)+ 趋势(上 / 下,自动配色)+ 千分位 + 精度。
 
@@ -23,28 +24,47 @@ package: "@teamix-evo/ui"
 - 表格内数字 → 直接 `<td className="tabular-nums">`
 - 图表 → `Chart`(本仓暂未提供)
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `title` | `React.ReactNode` | – | – | 标题(antd `title` 并集)。 |
-| `value` | `number \| string` | – | ✓ | 数值(antd `value` 并集)。 |
-| `prefix` | `React.ReactNode` | – | – | 前缀(图标 / 货币符号 / 单位)。 |
-| `suffix` | `React.ReactNode` | – | – | 后缀(单位 / 趋势)。 |
-| `precision` | `number` | – | – | 数值精度(antd `precision` 并集),仅 number 生效。 |
-| `groupSeparator` | `boolean` | `true` | – | 千分位分隔符。 |
-| `trend` | `'up' \| 'down' \| 'none'` | `"none"` | – | 趋势 — `up`(绿色 ↑)/ `down`(红色 ↓)/ `none`。前置在数值上方或左侧。 |
-| `trendValue` | `string \| number` | – | – | 趋势百分比文字(配 trend 显示在 suffix 区)。 |
-| `valueClassName` | `string` | – | – | 数值颜色覆盖(默认随 trend / 否则 foreground)。 |
+
+#### Statistic
+
+| 名称             | 类型                       | 默认值   | 必填 | 说明                                                                |
+| ---------------- | -------------------------- | -------- | ---- | ------------------------------------------------------------------- |
+| `title`          | `React.ReactNode`          | –        | –    | 标题(antd `title` 并集)。                                           |
+| `value`          | `number \| string`         | –        | ✓    | 数值(antd `value` 并集)。                                           |
+| `prefix`         | `React.ReactNode`          | –        | –    | 前缀(图标 / 货币符号 / 单位)。                                      |
+| `suffix`         | `React.ReactNode`          | –        | –    | 后缀(单位 / 趋势)。                                                 |
+| `precision`      | `number`                   | –        | –    | 数值精度(antd `precision` 并集),仅 number 生效。                    |
+| `groupSeparator` | `boolean`                  | `true`   | –    | 千分位分隔符。                                                      |
+| `trend`          | `'up' \| 'down' \| 'none'` | `"none"` | –    | 趋势 — `up`(绿色 ↑)/ `down`(红色 ↓)/ `none`。前置在数值上方或左侧。 |
+| `trendValue`     | `string \| number`         | –        | –    | 趋势百分比文字(配 trend 显示在 suffix 区)。                         |
+| `valueClassName` | `string`                   | –        | –    | 数值颜色覆盖(默认随 trend / 否则 foreground)。                      |
+
+#### StatisticTimer
+
+| 名称       | 类型                       | 默认值        | 必填 | 说明                                                          |
+| ---------- | -------------------------- | ------------- | ---- | ------------------------------------------------------------- |
+| `type`     | `'countdown' \| 'countup'` | `"countdown"` | –    | 计时类型 — `countdown` 倒计时到 `target`;`countup` 向上计时。 |
+| `target`   | `number`                   | –             | –    | 目标时间(毫秒时间戳)。`countdown` 必填;`countup` 可选。       |
+| `format`   | `string`                   | `"HH:mm:ss"`  | –    | 时间格式化字符串 — 支持 `HH` `mm` `ss` `SSS`(毫秒);`D` 天数。 |
+| `onFinish` | `() => void`               | –             | –    | 倒计时到达 0 / 计时到达 target 时回调。                       |
+| `onChange` | `(msLeft: number) => void` | –             | –    | 每次 tick 回调。                                              |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add statistic` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -53,6 +73,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/statistic/statistic.stories.tsx

@@ -11,7 +11,7 @@ const meta: Meta<typeof Statistic> = {
     docs: {
       description: {
         component:
-          '数字展示 — 仪表板核心指标。大字号 + 千分位 + 精度 + 前后缀 + 趋势(上 / 下,自动配色)。OpenTrek tokens 适配,等价 antd Statistic。',
+          '数字展示 — 仪表板核心指标。大字号 + 千分位 + 精度 + 前后缀 + 趋势（上 / 下，自动配色）。等价 antd Statistic。',
       },
     },
   },
@@ -59,11 +59,7 @@ export const InCards: Story = {
       </Card>
       <Card>
         <CardContent className="pt-6">
-          <Statistic
-            title="活跃用户"
-            value={12480}
-            prefix={<Users />}
-          />
+          <Statistic title="活跃用户" value={12480} prefix={<Users />} />
         </CardContent>
       </Card>
     </div>

package/src/components/statistic/statistic.tsx

@@ -42,7 +42,7 @@ function formatNumber(
 }
 
 const trendStyles = {
-  up: 'text-emerald-600',
+  up: 'text-success',
   down: 'text-destructive',
   none: '',
 } as const;

package/src/components/steps/steps.meta.md

@@ -1,13 +1,14 @@
 ---
 id: steps
 name: Steps
+displayName: 步骤条
 type: component
 category: navigation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Steps
+# Steps 步骤条
 
 步骤条 — antd 独有补足。引导用户完成多步流程(注册 / 下单 / 部署),清晰展示当前 / 已完成 / 待完成 / 错误状态。
 
@@ -23,24 +24,31 @@ package: "@teamix-evo/ui"
 - 简单进度 → `Progress` / `ProgressCircle`
 - 历史时间线 → 自定义 timeline(暂无组件)
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `items` | `StepItem[]` | – | ✓ | 步骤列表。 |
-| `current` | `number` | `0` | – | 当前步骤(0-based)。`current` 之前的为 finish,`current` 为 process,之后为 wait。 |
-| `status` | `'process' \| 'error'` | `"process"` | – | 当前步骤的状态(只影响 `current` 那一步;`process` 默认,`error` 标红)。 |
-| `direction` | `'horizontal' \| 'vertical'` | `"horizontal"` | – | 排列方向。 |
-| `size` | `'sm' \| 'default'` | `"default"` | – | 尺寸。 |
+
+| 名称        | 类型                         | 默认值         | 必填 | 说明                                                                            |
+| ----------- | ---------------------------- | -------------- | ---- | ------------------------------------------------------------------------------- |
+| `items`     | `StepItem[]`                 | –              | ✓    | 步骤列表。                                                                      |
+| `current`   | `number`                     | `0`            | –    | 当前步骤(0-based)。`current` 之前的为 finish,`current` 为 process,之后为 wait。 |
+| `status`    | `'process' \| 'error'`       | `"process"`    | –    | 当前步骤的状态(只影响 `current` 那一步;`process` 默认,`error` 标红)。           |
+| `direction` | `'horizontal' \| 'vertical'` | `"horizontal"` | –    | 排列方向。                                                                      |
+| `size`      | `'sm' \| 'default'`          | `"default"`    | –    | 尺寸。                                                                          |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add steps` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -49,6 +57,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
+
 <!-- auto:deps:end -->
 
 > `StepItem` 类型:`{ title; description?; status?: 'wait' | 'process' | 'finish' | 'error'; icon? }`。

package/src/components/steps/steps.stories.tsx

@@ -9,7 +9,7 @@ const meta: Meta<typeof Steps> = {
     docs: {
       description: {
         component:
-          '步骤条 — 引导多步流程(注册 / 下单 / 部署)。状态自动推导(wait/process/finish/error),支持横向 / 纵向、两种尺寸、自定义图标。OpenTrek tokens 适配。',
+          '步骤条 — 引导多步流程(注册 / 下单 / 部署)。状态自动推导(wait/process/finish/error),支持横向 / 纵向、两种尺寸、自定义图标。',
       },
     },
   },
@@ -19,7 +19,12 @@ const meta: Meta<typeof Steps> = {
     direction: { control: 'inline-radio', options: ['horizontal', 'vertical'] },
     size: { control: 'inline-radio', options: ['sm', 'default'] },
   },
-  args: { current: 1, status: 'process', direction: 'horizontal', size: 'default' },
+  args: {
+    current: 1,
+    status: 'process',
+    direction: 'horizontal',
+    size: 'default',
+  },
 };
 
 export default meta;

package/src/components/switch/switch.meta.md

@@ -1,13 +1,14 @@
 ---
 id: switch
 name: Switch
+displayName: 开关
 type: component
 category: form
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Switch
+# Switch 开关
 
 开关 — Radix Switch + antd 的 `loading / checkedChildren / unCheckedChildren / size`。
 
@@ -26,12 +27,14 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `loading` | `boolean` | `false` | – | 加载态 — 自动 `disabled`,thumb 上叠加自旋 spinner(antd 并集)。 |
-| `checkedChildren` | `React.ReactNode` | – | – | 选中态显示的内文(antd `checkedChildren` 并集)。 |
-| `unCheckedChildren` | `React.ReactNode` | – | – | 未选中态显示的内文(antd `unCheckedChildren` 并集)。 |
-| `size` | `'sm' \| 'default'` | `"default"` | – | 尺寸。 |
+
+| 名称                | 类型                | 默认值      | 必填 | 说明                                                           |
+| ------------------- | ------------------- | ----------- | ---- | -------------------------------------------------------------- |
+| `loading`           | `boolean`           | `false`     | –    | 加载态 — 自动 `disabled`,thumb 上叠加自旋 spinner(antd 并集)。 |
+| `checkedChildren`   | `React.ReactNode`   | –           | –    | 选中态显示的内文(antd `checkedChildren` 并集)。                |
+| `unCheckedChildren` | `React.ReactNode`   | –           | –    | 未选中态显示的内文(antd `unCheckedChildren` 并集)。            |
+| `size`              | `'sm' \| 'default'` | `"default"` | –    | 尺寸。                                                         |
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -39,13 +42,14 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add switch` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -54,6 +58,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add @radix-ui/react-switch@^1.1.0 lucide-react@^0.460.0
 ```
+
 <!-- auto:deps:end -->
 
 > 透传所有 Radix Switch.Root props(`checked` / `defaultChecked` / `onCheckedChange` / `name` / `value` 等)。

package/src/components/switch/switch.stories.tsx

@@ -9,7 +9,7 @@ const meta: Meta<typeof Switch> = {
     docs: {
       description: {
         component:
-          '开关 — 在开 / 关两种状态间切换，适用于需要即时生效的二值设置。Radix Switch 实现 + antd Switch 的并集能力：支持 `size` (sm / default)、`loading` 异步状态、以及 `checkedChildren` / `unCheckedChildren` 在轨道内渲染状态文本（对齐 antd）。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '开关 — 在开 / 关两种状态间切换，适用于需要即时生效的二值设置。Radix Switch 实现 + antd Switch 的并集能力：支持 `size` (sm / default)、`loading` 异步状态、以及 `checkedChildren` / `unCheckedChildren` 在轨道内渲染状态文本（对齐 antd）。',
       },
     },
   },

package/src/components/switch/switch.tsx

@@ -39,59 +39,81 @@ const Switch = React.forwardRef<
     ref,
   ) => {
     const isSm = size === 'sm';
+    const hasInner = checkedChildren != null || unCheckedChildren != null;
+    const thumbSize = isSm ? 'size-4' : 'size-5';
+    const spinnerSize = isSm ? 'size-3' : 'size-3.5';
+    const renderThumb = (extra?: string) => (
+      <SwitchPrimitive.Thumb
+        className={cn(
+          'pointer-events-none flex shrink-0 items-center justify-center rounded-full bg-background shadow-lg ring-0',
+          thumbSize,
+          extra,
+        )}
+      >
+        {loading ? (
+          <Loader2
+            className={cn(
+              'animate-spin text-muted-foreground motion-reduce:animate-none',
+              spinnerSize,
+            )}
+            aria-hidden="true"
+          />
+        ) : null}
+      </SwitchPrimitive.Thumb>
+    );
+
     return (
       <SwitchPrimitive.Root
         ref={ref}
         disabled={disabled || loading}
         className={cn(
-          'peer relative inline-flex shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input',
-          isSm ? 'h-5 w-9' : 'h-6 w-11',
+          'peer group inline-flex shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input',
+          hasInner
+            ? cn(
+                // 内文模式：高度固定，宽度按 thumb + 文字 + gap + padding 自适应
+                isSm ? 'h-5 min-w-9 gap-1' : 'h-6 min-w-11 gap-1.5',
+              )
+            : cn(isSm ? 'h-5 w-9' : 'h-6 w-11'),
           className,
         )}
         {...props}
       >
-        {/* Inner labels (checkedChildren / unCheckedChildren) */}
-        {checkedChildren != null || unCheckedChildren != null ? (
+        {hasInner ? (
           <>
+            {/* thumb 与文字以 flex order 互换位置 */}
+            {renderThumb('order-1 group-data-[state=checked]:order-2')}
             <span
               className={cn(
-                'pointer-events-none absolute select-none text-[10px] font-medium leading-none text-primary-foreground transition-opacity peer-data-[state=unchecked]:opacity-0',
-                isSm ? 'left-1.5' : 'left-2',
-              )}
-              aria-hidden="true"
-            >
-              {checkedChildren}
-            </span>
-            <span
-              className={cn(
-                'pointer-events-none absolute select-none text-[10px] font-medium leading-none text-muted-foreground transition-opacity peer-data-[state=checked]:opacity-0',
-                isSm ? 'right-1.5' : 'right-2',
+                'pointer-events-none select-none font-medium leading-none',
+                isSm ? 'text-xxs' : 'text-xs',
+                'order-2 group-data-[state=checked]:order-1',
+                'group-data-[state=checked]:text-primary-foreground',
+                'group-data-[state=unchecked]:text-muted-foreground',
+                // 文字外侧 padding（远离 thumb 的一侧）—— thumb 侧不加 padding，与其他 switch 一致紧贴边缘
+                isSm
+                  ? 'group-data-[state=unchecked]:pr-1 group-data-[state=checked]:pl-1'
+                  : 'group-data-[state=unchecked]:pr-1.5 group-data-[state=checked]:pl-1.5',
               )}
               aria-hidden="true"
             >
-              {unCheckedChildren}
+              <span className="group-data-[state=unchecked]:hidden">
+                {checkedChildren}
+              </span>
+              <span className="group-data-[state=checked]:hidden">
+                {unCheckedChildren}
+              </span>
             </span>
           </>
-        ) : null}
-
-        <SwitchPrimitive.Thumb
-          className={cn(
-            'pointer-events-none flex items-center justify-center rounded-full bg-background shadow-lg ring-0 transition-transform',
-            isSm
-              ? 'size-4 data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0'
-              : 'size-5 data-[state=checked]:translate-x-5 data-[state=unchecked]:translate-x-0',
-          )}
-        >
-          {loading ? (
-            <Loader2
-              className={cn(
-                'animate-spin text-muted-foreground motion-reduce:animate-none',
-                isSm ? 'size-3' : 'size-3.5',
-              )}
-              aria-hidden="true"
-            />
-          ) : null}
-        </SwitchPrimitive.Thumb>
+        ) : (
+          renderThumb(
+            cn(
+              'transition-transform',
+              isSm
+                ? 'data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0'
+                : 'data-[state=checked]:translate-x-5 data-[state=unchecked]:translate-x-0',
+            ),
+          )
+        )}
       </SwitchPrimitive.Root>
     );
   },

package/src/components/table/table.meta.md

@@ -1,13 +1,14 @@
 ---
 id: table
 name: Table
+displayName: 表格
 type: component
 category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Table
+# Table 表格
 
 基础表格 — 原生 HTML 元素薄包装。**仅视觉与可访问性骨架**(列宽 / 边框 / hover / 选中态);**无排序 / 筛选 / 分页 / 数据流**(那是 `DataTable` 的范畴)。
 
@@ -28,7 +29,9 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
+
 _(组件无 `<Name>Props` interface — props 详见 [`table.tsx`](./table.tsx))_
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -36,17 +39,19 @@ _(组件无 `<Name>Props` interface — props 详见 [`table.tsx`](./table.tsx))
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add table` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
+
 <!-- auto:deps:end -->
 
 > 子组件:`Table` / `TableHeader`(thead)/ `TableBody`(tbody)/ `TableFooter`(tfoot)/ `TableHead`(th)/ `TableRow`(tr)/ `TableCell`(td)/ `TableCaption`(caption)。
@@ -63,7 +68,13 @@ _无 — 本组件不依赖任何 npm 包。_
 
 ```tsx
 import {
-  Table, TableHeader, TableBody, TableHead, TableRow, TableCell, TableCaption,
+  Table,
+  TableHeader,
+  TableBody,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
 } from '@/components/ui/table';
 import { Badge } from '@/components/ui/badge';
 
@@ -80,16 +91,20 @@ import { Badge } from '@/components/ui/badge';
   <TableBody>
     <TableRow>
       <TableCell className="font-medium">INV001</TableCell>
-      <TableCell><Badge variant="success">已支付</Badge></TableCell>
+      <TableCell>
+        <Badge variant="success">已支付</Badge>
+      </TableCell>
       <TableCell>信用卡</TableCell>
       <TableCell className="text-right">¥250.00</TableCell>
     </TableRow>
     <TableRow data-state="selected">
       <TableCell className="font-medium">INV002</TableCell>
-      <TableCell><Badge>待支付</Badge></TableCell>
+      <TableCell>
+        <Badge>待支付</Badge>
+      </TableCell>
       <TableCell>转账</TableCell>
       <TableCell className="text-right">¥150.00</TableCell>
     </TableRow>
   </TableBody>
-</Table>
+</Table>;
 ```

package/src/components/table/table.stories.tsx

@@ -15,6 +15,14 @@ const meta: Meta<typeof Table> = {
   title: '数据展示 · Data Display/Table',
   component: Table,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '基础表格 — 原生 HTML 元素薄包装，仅提供视觉与可访问性骨架（列宽 / 边框 / hover / 选中态）。无排序 / 筛选 / 分页 / 数据流，复杂场景请用 `DataTable`。',
+      },
+    },
+  },
 };
 
 export default meta;
@@ -63,10 +71,7 @@ export const Default: Story = {
         <TableRow>
           <TableCell colSpan={3}>合计</TableCell>
           <TableCell className="text-right tabular-nums">
-            ¥
-            {invoices
-              .reduce((sum, x) => sum + x.amount, 0)
-              .toFixed(2)}
+            ¥{invoices.reduce((sum, x) => sum + x.amount, 0).toFixed(2)}
           </TableCell>
         </TableRow>
       </TableFooter>