@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/spinner/spinner.tsx

@@ -8,18 +8,19 @@ const spinnerVariants = cva('inline-block shrink-0 animate-spin', {
   variants: {
     size: {
       sm: 'size-3',
+      md: 'size-4',
       default: 'size-4',
       lg: 'size-6',
       xl: 'size-8',
     },
-    tone: {
+    color: {
       default: 'text-foreground',
       muted: 'text-muted-foreground',
       primary: 'text-primary',
       destructive: 'text-destructive',
     },
   },
-  defaultVariants: { size: 'default', tone: 'default' },
+  defaultVariants: { size: 'default', color: 'default' },
 });
 
 export interface SpinnerProps
@@ -29,12 +30,12 @@ export interface SpinnerProps
    * 尺寸 — 与 antd Spin 的 small/middle/large 对齐(加 xl 用于全屏 loading)。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg' | 'xl';
+  size?: 'sm' | 'md' | 'default' | 'lg' | 'xl';
   /**
-   * 配色 — `muted` 走次级文本色;`primary` / `destructive` 走语义色。
+   * 配色 — `muted` 走次级文本色;`primary` / `destructive` 走语义色。对齐 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md)。
    * @default "default"
    */
-  tone?: 'default' | 'muted' | 'primary' | 'destructive';
+  color?: 'default' | 'muted' | 'primary' | 'destructive';
   /**
    * 给读屏器的描述(默认 "Loading...")。
    */
@@ -43,10 +44,10 @@ export interface SpinnerProps
 
 /**
  * 简单旋转 loading — shadcn 2025-10 新增,等价 antd `Spin`(无遮罩版)。
- * 需要"包裹内容显示遮罩 loading"时配合 `Skeleton` 或自行包一层。
+ * 需要"包裹内容显示遮罩 loading"时使用配套的 `SpinnerOverlay`。
  */
 const Spinner = React.forwardRef<HTMLSpanElement, SpinnerProps>(
-  ({ size, tone, label = 'Loading...', className, ...props }, ref) => (
+  ({ size, color, label = 'Loading...', className, ...props }, ref) => (
     <span
       ref={ref}
       role="status"
@@ -54,11 +55,112 @@ const Spinner = React.forwardRef<HTMLSpanElement, SpinnerProps>(
       className={cn('inline-flex items-center', className)}
       {...props}
     >
-      <Loader2 className={cn(spinnerVariants({ size, tone }))} aria-hidden="true" />
+      <Loader2
+        className={cn(spinnerVariants({ size, color }))}
+        aria-hidden="true"
+      />
       <span className="sr-only">{label}</span>
     </span>
   ),
 );
 Spinner.displayName = 'Spinner';
 
-export { Spinner, spinnerVariants };
+// ─── SpinnerOverlay(antd `Spin` wrap children 并集)─────────────────────────
+
+export interface SpinnerOverlayProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /**
+   * 是否处于加载中 — `true` 时渲染半透明遮罩 + 居中 spinner;`false` 时仅渲染 children。
+   * @default true
+   */
+  loading?: boolean;
+  /**
+   * 内层 spinner 尺寸(透传给 [`Spinner`](./spinner.tsx) 的 `size`)。
+   * @default "lg"
+   */
+  size?: SpinnerProps['size'];
+  /**
+   * 内层 spinner 配色(透传给 [`Spinner`](./spinner.tsx) 的 `color`)。
+   * @default "primary"
+   */
+  color?: SpinnerProps['color'];
+  /**
+   * 图标下方的提示文案(antd `Spin.tip` 并集);为空则只渲染 spinner。
+   */
+  tip?: React.ReactNode;
+  /**
+   * 被包裹的内容 — 加载中时仍渲染但被遮罩覆盖,占据原有空间不抖动。
+   */
+  children?: React.ReactNode;
+  /**
+   * 是否对内容做高斯模糊(配合半透明遮罩,营造 "内容被禁用" 视感)。
+   * @default false
+   */
+  blur?: boolean;
+}
+
+/**
+ * 包裹内容的加载遮罩 — 等价 antd `<Spin>{children}</Spin>` 的 wrap children 形态。
+ * 加载中时:外层 `relative` 容器 + 半透明遮罩 + 居中 spinner + 可选 tip;
+ * 非加载中时:children 透传,无任何额外节点(零运行时开销)。
+ *
+ * 实现纪律:
+ *   - 不内嵌别的容器样式 — 由消费方决定 Card / Section / 自定义边框
+ *   - 遮罩用 `bg-background/60 backdrop-blur-[1px]` 走 OpenTrek tokens,无字面色
+ *   - 加载中保留 children 在 DOM(`aria-busy="true"`),不做条件渲染避免布局抖动
+ */
+const SpinnerOverlay = React.forwardRef<HTMLDivElement, SpinnerOverlayProps>(
+  (
+    {
+      loading = true,
+      size = 'lg',
+      color = 'primary',
+      tip,
+      blur = false,
+      className,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    if (!loading) {
+      return (
+        <div ref={ref} className={cn('relative', className)} {...props}>
+          {children}
+        </div>
+      );
+    }
+    return (
+      <div
+        ref={ref}
+        aria-busy="true"
+        className={cn('relative', className)}
+        {...props}
+      >
+        <div
+          aria-hidden="true"
+          className={cn(
+            'pointer-events-none transition-[filter,opacity] duration-200',
+            blur && 'opacity-60 blur-[1px]',
+          )}
+        >
+          {children}
+        </div>
+        <div
+          className={cn(
+            'absolute inset-0 z-10 flex flex-col items-center justify-center gap-2',
+            'bg-background/60 backdrop-blur-[1px]',
+          )}
+        >
+          <Spinner size={size} color={color} />
+          {tip ? (
+            <span className="text-xs text-muted-foreground">{tip}</span>
+          ) : null}
+        </div>
+      </div>
+    );
+  },
+);
+SpinnerOverlay.displayName = 'SpinnerOverlay';
+
+export { Spinner, SpinnerOverlay, spinnerVariants };

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,6 +24,8 @@ package: "@teamix-evo/ui"
 - 表格内数字 → 直接 `<td className="tabular-nums">`
 - 图表 → `Chart`(本仓暂未提供)
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -37,6 +40,8 @@ package: "@teamix-evo/ui"
 | `valueClassName` | `string` | – | – | 数值颜色覆盖(默认随 trend / 否则 foreground)。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 

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

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { ShoppingCart, Users } from 'lucide-react';
 import { Statistic } from './statistic';
 import { Card, CardContent } from '@/components/card/card';
@@ -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

@@ -33,8 +33,7 @@ function formatNumber(
   precision?: number,
   groupSeparator = true,
 ): string {
-  const fixed =
-    precision !== undefined ? v.toFixed(precision) : v.toString();
+  const fixed = precision !== undefined ? v.toFixed(precision) : v.toString();
   if (!groupSeparator) return fixed;
   const [intPart, decPart] = fixed.split('.');
   const grouped = intPart!.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
@@ -42,7 +41,7 @@ function formatNumber(
 }
 
 const trendStyles = {
-  up: 'text-emerald-600',
+  up: 'text-success',
   down: 'text-destructive',
   none: '',
 } as const;
@@ -77,7 +76,7 @@ const Statistic = React.forwardRef<HTMLDivElement, StatisticProps>(
         {...props}
       >
         {title ? (
-          <div className="text-sm text-muted-foreground">{title}</div>
+          <div className="text-xs text-muted-foreground">{title}</div>
         ) : null}
         <div
           className={cn(
@@ -91,12 +90,12 @@ const Statistic = React.forwardRef<HTMLDivElement, StatisticProps>(
           ) : null}
           <span>{display}</span>
           {suffix ? (
-            <span className="text-sm font-normal text-muted-foreground">
+            <span className="text-xs font-normal text-muted-foreground">
               {suffix}
             </span>
           ) : null}
           {TrendIcon ? (
-            <span className="inline-flex items-baseline gap-0.5 text-sm font-medium">
+            <span className="inline-flex items-baseline gap-0.5 text-xs font-medium">
               <TrendIcon className="size-3" />
               {trendValue}
             </span>

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,6 +24,8 @@ package: "@teamix-evo/ui"
 - 简单进度 → `Progress` / `ProgressCircle`
 - 历史时间线 → 自定义 timeline(暂无组件)
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -30,9 +33,11 @@ package: "@teamix-evo/ui"
 | `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"` | – | 尺寸。 |
+| `size` | `'sm' \| 'md' \| 'default'` | `"default"` | – | 尺寸。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -51,12 +56,21 @@ pnpm add lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
-> `StepItem` 类型:`{ title; description?; status?: 'wait' | 'process' | 'finish' | 'error'; icon? }`。
+> `StepItem` 类型:`{ title; description?; status?: 'wait' | 'process' | 'finish' | 'error' | 'disabled'; icon? }`。5 状态视觉区分:
+>
+> | 状态 | 圆点 | 连线 | 标题 | 交互 |
+> | --- | --- | --- | --- | --- |
+> | `wait` | 描边 + muted | border | muted | 可点击 |
+> | `process` | primary 填充 + shadow | border | foreground + medium | 可点击 |
+> | `finish` | primary 填充 + Check | primary | foreground | 可点击 |
+> | `error` | destructive 填充 + X | border | destructive + medium | 可点击 |
+> | `disabled` | muted + opacity-60 | border + opacity-60 | muted + opacity-60 | `pointer-events: none` + `aria-disabled` |
 
 ## AI 生成纪律
 
 - **`current` 0-based**:第一步是 0,与数组索引一致
 - **`status="error"` 仅当前步**:把整体状态置错;**不要**对历史已完成步标 error
+- **单项 `disabled`**:用 `StepItem.status: 'disabled'` 表示该步不可点击(需升级 / 该路径不适用),视觉 muted 变深 + 60% 透明度 + 提示 `aria-disabled`
 - **`description` 简短**:不超过 1 行,长说明放主区
 - **vertical 用于侧栏**:横向用于宽屏 / 顶部
 - **不要堆叠超过 6 步**:认知超载;> 6 步改用 Wizard 模式 + 折叠

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

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Steps } from './steps';
 
 const meta: Meta<typeof Steps> = {
@@ -9,7 +9,7 @@ const meta: Meta<typeof Steps> = {
     docs: {
       description: {
         component:
-          '步骤条 — 引导多步流程(注册 / 下单 / 部署)。状态自动推导(wait/process/finish/error),支持横向 / 纵向、两种尺寸、自定义图标。OpenTrek tokens 适配。',
+          'Steps 步骤条 — 在多步流程(注册 / 下单 / 部署)中明示当前阶段与整体进度。**antd 独有补足**，shadcn 未提供对应原子；API 能力取 antd `Steps` 起点并保留准则需要的子集：`current` / `status` / `direction` / `size` / `StepItem.status`(`wait` / `process` / `finish` / `error` / `disabled` 5 状态) / `StepItem.icon`。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/tokens`，无 mock。',
       },
     },
   },
@@ -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;
@@ -73,3 +78,38 @@ export const Small: Story = {
     </div>
   ),
 };
+
+export const AllStatuses: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-[720px]">
+      <Steps
+        current={1}
+        items={[
+          { title: 'Finish', description: '已完成', status: 'finish' },
+          { title: 'Process', description: '进行中', status: 'process' },
+          { title: 'Wait', description: '等待中', status: 'wait' },
+          { title: 'Error', description: '处理失败', status: 'error' },
+          { title: 'Disabled', description: '不可点击', status: 'disabled' },
+        ]}
+      />
+    </div>
+  ),
+};
+
+export const DisabledStep: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-[600px]">
+      <Steps
+        current={0}
+        items={[
+          { title: '账户信息' },
+          { title: '验证邮箱' },
+          { title: '高级设置', status: 'disabled', description: '需升级后可用' },
+          { title: '完成' },
+        ]}
+      />
+    </div>
+  ),
+};

package/src/components/steps/steps.tsx

@@ -3,14 +3,14 @@ import { Check, X } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 
-export type StepStatus = 'wait' | 'process' | 'finish' | 'error';
+export type StepStatus = 'wait' | 'process' | 'finish' | 'error' | 'disabled';
 
 export interface StepItem {
   /** 步骤标题(必填)。 */
   title: React.ReactNode;
   /** 描述(可选)。 */
   description?: React.ReactNode;
-  /** 自定义状态(覆盖父级根据 current 推导出的状态)。 */
+  /** 自定义状态(覆盖父级根据 current 推导出的状态)。`disabled` 状态不响应点击。 */
   status?: StepStatus;
   /** 自定义图标(覆盖默认数字 / 勾选 / 错误)。 */
   icon?: React.ReactNode;
@@ -38,7 +38,7 @@ export interface StepsProps extends React.HTMLAttributes<HTMLDivElement> {
    * 尺寸。
    * @default "default"
    */
-  size?: 'sm' | 'default';
+  size?: 'sm' | 'md' | 'default';
 }
 
 function statusFor(
@@ -55,9 +55,10 @@ function statusFor(
 
 const dotColor: Record<StepStatus, string> = {
   wait: 'border-border bg-background text-muted-foreground',
-  process: 'border-primary bg-primary text-primary-foreground',
+  process: 'border-primary bg-primary text-primary-foreground shadow-sm',
   finish: 'border-primary bg-primary text-primary-foreground',
   error: 'border-destructive bg-destructive text-destructive-foreground',
+  disabled: 'border-border bg-muted text-muted-foreground opacity-60',
 };
 
 const lineColor: Record<StepStatus, string> = {
@@ -65,13 +66,15 @@ const lineColor: Record<StepStatus, string> = {
   process: 'bg-border',
   finish: 'bg-primary',
   error: 'bg-border',
+  disabled: 'bg-border opacity-60',
 };
 
 const titleColor: Record<StepStatus, string> = {
   wait: 'text-muted-foreground',
   process: 'text-foreground font-medium',
   finish: 'text-foreground',
-  error: 'text-destructive',
+  error: 'text-destructive font-medium',
+  disabled: 'text-muted-foreground opacity-60',
 };
 
 const Steps = React.forwardRef<HTMLDivElement, StepsProps>(
@@ -81,14 +84,14 @@ const Steps = React.forwardRef<HTMLDivElement, StepsProps>(
       current = 0,
       status = 'process',
       direction = 'horizontal',
-      size = 'default',
+      size = 'md',
       className,
       ...props
     },
     ref,
   ) => {
     const isVertical = direction === 'vertical';
-    const dotSize = size === 'sm' ? 'size-6 text-xs' : 'size-8 text-sm';
+    const dotSize = size === 'sm' ? 'size-6 text-xs' : 'size-8 text-xs';
     return (
       <div
         ref={ref}
@@ -102,6 +105,7 @@ const Steps = React.forwardRef<HTMLDivElement, StepsProps>(
         {items.map((it, i) => {
           const s = statusFor(i, current, status, it.status);
           const isLast = i === items.length - 1;
+          const isDisabled = s === 'disabled';
           const icon =
             it.icon ??
             (s === 'finish' ? (
@@ -114,9 +118,11 @@ const Steps = React.forwardRef<HTMLDivElement, StepsProps>(
           return (
             <div
               key={i}
+              aria-disabled={isDisabled || undefined}
               className={cn(
                 'flex flex-1',
                 isVertical ? 'flex-row gap-3' : 'flex-col gap-2',
+                isDisabled && 'pointer-events-none',
               )}
             >
               <div
@@ -146,12 +152,9 @@ const Steps = React.forwardRef<HTMLDivElement, StepsProps>(
                 ) : null}
               </div>
               <div
-                className={cn(
-                  'flex flex-col gap-0.5',
-                  !isVertical && 'pr-3',
-                )}
+                className={cn('flex flex-col gap-0.5', !isVertical && 'pr-3')}
               >
-                <div className={cn('text-sm', titleColor[s])}>{it.title}</div>
+                <div className={cn('text-xs', titleColor[s])}>{it.title}</div>
                 {it.description ? (
                   <div className="text-xs text-muted-foreground">
                     {it.description}

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

@@ -1,13 +1,14 @@
 ---
 id: switch
 name: Switch
+displayName: 开关
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Switch
+# Switch 开关
 
 开关 — Radix Switch + antd 的 `loading / checkedChildren / unCheckedChildren / size`。
 
@@ -28,10 +29,18 @@ package: "@teamix-evo/ui"
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
+| `checked` | `boolean` | – | – | 受控选中状态(等价 antd `checked`)。 与 `defaultChecked` 二选一,不同时传。 |
+| `defaultChecked` | `boolean` | `false` | – | 非受控初始选中态(等价 antd `defaultChecked`)。 |
+| `onCheckedChange` | `(checked: boolean) => void` | – | – | 选中状态变化回调 — Radix 命名,等价 antd `onChange(checked)`。 |
+| `disabled` | `boolean` | `false` | – | 禁用整个 Switch(灰化 + 不响应交互)。`loading` 也会自动禁用。 |
+| `required` | `boolean` | `false` | – | 表单必填 — 设置 HTML 原生 `required`,表单层校验依赖此值。 |
+| `name` | `string` | – | – | 表单字段名(原生 `<input name>`,提交表单时使用)。 |
+| `value` | `string` | – | – | 表单字段值(选中时随表单提交)。 |
+| `id` | `string` | – | – | id 属性,配合 `<label htmlFor>` 关联标签。 |
 | `loading` | `boolean` | `false` | – | 加载态 — 自动 `disabled`,thumb 上叠加自旋 spinner(antd 并集)。 |
 | `checkedChildren` | `React.ReactNode` | – | – | 选中态显示的内文(antd `checkedChildren` 并集)。 |
 | `unCheckedChildren` | `React.ReactNode` | – | – | 未选中态显示的内文(antd `unCheckedChildren` 并集)。 |
-| `size` | `'sm' \| 'default'` | `"default"` | – | 尺寸。 |
+| `size` | `'sm' \| 'md' \| 'default'` | `"md"` | – | 尺寸。`md` 与 `default` 完全等价,后者作为向后兼容别名保留;新代码请优先 使用 `md`,与 Button / Input / Checkbox / Radio 等表单原子组件的 size enum 一致。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -63,7 +72,11 @@ pnpm add @radix-ui/react-switch@^1.1.0 lucide-react@^0.460.0
 - **`loading` 期间禁止操作**:已自动 `disabled`,**不要**手动叠加 disabled 影响 UX 一致
 - **`checkedChildren` 文字 ≤ 2 个汉字**:仅"开/关"或"On/Off",过长会溢出胶囊
 - **配 Label 无障碍**:Switch 不带可见文字时,必须用 `aria-label` 或外部 `<Label>` + `id` 关联
-- **size="sm" 用于密集列表**:常规表单用 `default`
+- **size 命名**:首选 `'sm' | 'md'`,与 Button / Input / Checkbox / Radio 等表单原子保持一致;`'default'` 作为向后兼容别名保留(等价 `'md'`)
+- **size 对齐 cloud-design**:`sm` 外框 16x28(h-4 w-7) 对齐旧库 `small`,`md`/`default` 外框 24x44(h-6 w-11) 对齐旧库 `medium`,**不要随意改尺寸**(会与表单/表格里的密集布局打架)
+- **内文模式 sm 限制**:`sm` 下内文使用 10px 字号(inline style,绕开 `no-arbitrary-tw-value`),实际可视宽度仅够容纳 1 个汉字(如"开/关");如需多字请用 `md` size
+- **thumb 紧贴边缘规范**:开/关两态下 thumb 始终紧贴 track 一侧;有 `checkedChildren / unCheckedChildren` 时,文字 span 仅在 thumb 反向加 padding,thumb 与轨道边缘距离对称(checked: thumb 贴右,文字偏左 padding;unchecked: thumb 贴左,文字偏右 padding)
+- **inner text 自适应宽度**:文字态下 track `min-w` 弹性,文字 span 通过 `flex-1` + 单侧 padding 撑开容器,**不要给 track 写死 w-\* 数值**
 
 ## Examples
 
@@ -89,4 +102,37 @@ const [on, setOn] = React.useState(false);
 
 // 小尺寸
 <Switch size="sm" />
+
+// md(推荐写法,与 Button/Input/Checkbox 一致)
+<Switch size="md" />
 ```
+
+## Switch 形态 — 旧库 API → 新映射
+
+> 决策:**不新增独立组件**,直接在 `@teamix-evo/ui Switch` 上承接 cloud-design `Switch` 的所有有效用法。本章节是从旧库平滑迁移的查表索引,与 [上面的 Props 表](#props) 互补。
+
+### Props 映射
+
+| cloud-design `Switch`                   | `@teamix-evo/ui Switch`         | 说明                                              |
+| --------------------------------------- | ------------------------------- | ------------------------------------------------- |
+| `checked` / `defaultChecked`            | 同名                            | 透传 Radix `Switch.Root`                          |
+| `onChange(checked, e)`                  | `onCheckedChange(checked)`      | Radix 命名,签名仅返回 `boolean`(无 event 形参)    |
+| `disabled`                              | 同名                            | 透传                                              |
+| `size="small"`                          | `size="sm"`                     | 命名对齐(与 Button/Input/Checkbox 同 enum)        |
+| `size="medium"`                         | `size="md"` 或 `size="default"` | `md` 为新写法,`default` 作为兼容别名保留          |
+| `loading`                               | 同名                            | 自动 `disabled` + thumb 上叠 spinner(antd 并集)   |
+| `checkedChildren` / `unCheckedChildren` | 同名                            | 透传,thumb 紧贴边缘 + 文字 span 单侧 padding 渲染 |
+| `autoWidth`(默认 true)                  | 内置行为                        | track `min-w` + 文字 span `flex-1`,无需 prop      |
+
+### 不修复 / 后续工序清单
+
+- **视觉尺寸 / 颜色微调**(40→36 / 22→20 / 18→16 / `#D9D9D9` → `#E5E5E5`):涉及 `@teamix-evo/tokens` 包,本次不动,留作 tokens 包 MVP 工序
+- **报告 §1/§3 的 "checkedChildren / unCheckedChildren 缺失" 描述过时**:实际本仓库自 0.1.0 起已完整实现(thumb 紧贴边缘 + 文字 span 单侧 padding + min-w 弹性宽度),无需补齐
+- **报告 §6 的 size 命名 `'medium'` → `'md'` 描述部分过时**:本仓库实际命名是 `'sm' | 'default'`,本次新增 `'md'` 别名后与其他原子组件对齐
+
+### Switch 专项 AI 生成纪律
+
+- 写新代码请优先用 `size="md"`,与 Button / Input / Checkbox / Radio 一致;遗留 `size="default"` 仍兼容,**不要主动批量改动**(避免无意义 diff)
+- `onCheckedChange` 签名只有 `(checked: boolean) => void`,**不要按旧库习惯**期待 `(checked, event)` 双参数
+- 受控模式 `checked` + `onCheckedChange` 必须配对;只写 `checked` 不写回调会冻结状态
+- 内文模式下 thumb / 文字的 padding 与 flex order 已在组件内固化,**不要在外层覆盖** `[&>span]:` 等 Tailwind 选择器

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

@@ -1,26 +1,26 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Switch } from './switch';
 
 const meta: Meta<typeof Switch> = {
-  title: '表单与输入 · Form/Switch',
+  title: '数据录入 · Data Entry/Switch',
   component: Switch,
   tags: ['autodocs'],
   parameters: {
     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）。',
       },
     },
   },
   argTypes: {
-    size: { control: 'inline-radio', options: ['sm', 'default'] },
+    size: { control: 'inline-radio', options: ['sm', 'md'] },
     loading: { control: 'boolean' },
     disabled: { control: 'boolean' },
     checkedChildren: { control: 'text' },
     unCheckedChildren: { control: 'text' },
   },
-  args: { size: 'default', loading: false, disabled: false },
+  args: { size: 'md', loading: false, disabled: false },
 };
 
 export default meta;
@@ -33,7 +33,7 @@ export const Sizes: Story = {
   render: () => (
     <div className="flex items-center gap-4">
       <Switch size="sm" defaultChecked />
-      <Switch size="default" defaultChecked />
+      <Switch size="md" defaultChecked />
     </div>
   ),
 };