@teamix-evo/ui 0.2.0 → 0.4.0

package/src/components/icon/icon.tsx

@@ -0,0 +1,248 @@
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/utils/cn';
+
+// ─── cva: 内层 svg 样式(承担 size + color + spin)─────────────────────────────
+//
+// `[&>svg]:size-full` 让 size class 应用到 span 后,svg 自动撑满容器。
+// 这样 ref / aria 类型都统一为 HTMLSpanElement,与 spinner 范本一致。
+
+export const iconInnerVariants = cva(
+  'inline-block shrink-0 align-[-0.125em] [&>svg]:size-full',
+  {
+    variants: {
+      size: {
+        xs: 'size-3', // 12px
+        sm: 'size-4', // 16px
+        md: 'size-5', // 20px(默认)
+        lg: 'size-6', // 24px
+        xl: 'size-7', // 28px
+        '2xl': 'size-9', // 36px
+        '3xl': 'size-12', // 48px
+        // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- `inherit` 档语义为跟随父级字号(em 单位),无法用 Tailwind token 刻度表达。
+        inherit: 'size-[1em]',
+      },
+      color: {
+        default: 'text-current',
+        muted: 'text-muted-foreground',
+        primary: 'text-primary',
+        success: 'text-success',
+        warning: 'text-warning',
+        destructive: 'text-destructive',
+      },
+      spin: { true: 'animate-spin' },
+    },
+    defaultVariants: { size: 'md', color: 'default' },
+  },
+);
+
+// ─── cva: 外层带背景容器(variant=circle/square 启用)──────────────────────
+//
+// 容器 size = inner size + 内边距,预留视觉舒适空间;inner svg 进入容器后什么都不变(1:1 联动),
+// 容器外边距由 size class 差(容器 size N → inner size N-2 → 单侧 padding 约 6–18px)推导。
+
+export const iconContainerVariants = cva(
+  'inline-flex items-center justify-center shrink-0',
+  {
+    variants: {
+      variant: {
+        plain: '',
+        circle: 'rounded-full',
+        square: 'rounded-md',
+      },
+      color: {
+        default: 'bg-muted text-foreground',
+        muted: 'bg-muted text-muted-foreground',
+        primary: 'bg-accent text-accent-foreground',
+        success: 'bg-success-subtle text-success',
+        warning: 'bg-warning-subtle text-warning',
+        destructive: 'bg-destructive/10 text-destructive',
+      },
+      size: {
+        xs: 'size-5', // 20px → inner xs(12px)
+        sm: 'size-6', // 24px → inner sm(16px)
+        md: 'size-8', // 32px → inner md(20px)
+        lg: 'size-10', // 40px → inner lg(24px)
+        xl: 'size-12', // 48px → inner xl(28px)
+        '2xl': 'size-14', // 56px → inner 2xl(36px)
+        '3xl': 'size-16', // 64px → inner 3xl(48px)
+        // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- `inherit` 档容器尺寸跟随父级字号(em 单位),无法用 Tailwind token 刻度表达。
+        inherit: 'size-[1.75em]',
+      },
+    },
+    defaultVariants: { variant: 'plain', color: 'default', size: 'md' },
+  },
+);
+
+export type IconInnerVariants = VariantProps<typeof iconInnerVariants>;
+export type IconContainerVariants = VariantProps<typeof iconContainerVariants>;
+
+// ─── Props ──────────────────────────────────────────────────────────────────
+
+type IconSize = NonNullable<IconInnerVariants['size']>;
+type IconColor = NonNullable<IconInnerVariants['color']>;
+type IconVariant = 'plain' | 'circle' | 'square';
+
+export interface IconProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /**
+   * 渲染目标 — 必填。lucide-react / 自定义 svg / iconfont 工厂返回的组件均可。
+   * 单一 children 通道,不再提供 `icon` prop(避免 `<Icon icon=...>` 组件名 + 同名 prop 的语义冗余)。
+   */
+  children: React.ReactNode;
+  /**
+   * 形态 — 决定是否带背景容器。
+   * - `plain`:无背景,size 直接控前景 svg(默认)
+   * - `circle` / `square`:带 `color` 配色的背景容器,inner svg 自动小一档
+   * @default "plain"
+   */
+  variant?: IconVariant;
+  /**
+   * 语义色 — 6 档枚举,字面与 OpenTrek tokens 对齐(见 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md))。
+   * - `variant=plain` 时控前景色
+   * - `variant=circle/square` 时同时控容器背景 + 前景(浅底深字)
+   * @default "default"
+   */
+  color?: IconColor;
+  /**
+   * 尺寸 — 7 档枚举 + inherit。`inherit` 走 `1em`,跟随父级字号(用于 Title / Button 内联场景)。
+   * 当 `variant!=plain` 时,该 size 指容器尺寸,inner svg 自动用对应小一档。
+   * @default "md"
+   */
+  size?: IconSize;
+  /**
+   * 旋转动效 — 与 antd Icon `spin` 对齐,Tailwind `animate-spin` 实现。
+   * @default false
+   */
+  spin?: boolean;
+  /**
+   * 静态旋转角度(度数)— 与 antd Icon `rotate` 对齐,通过 inline transform 实现。
+   * 与 `spin` 同时使用语义模糊,不建议同用。
+   */
+  rotate?: number;
+  /**
+   * Slot 模式 — 把渲染目标交给消费方提供的子元素。开启时 `variant` 强制走 plain。
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * 装饰性图标(默认 true,自动 `aria-hidden="true"`)。
+   * 当图标承载语义信息时设为 false,**必须**同时提供 `aria-label` 或被 `<button aria-label>` 包裹。
+   * @default true
+   */
+  decorative?: boolean;
+}
+
+// inner svg size class— 在带背景容器内使用(外层容器已提供 padding、flex 居中、color 前景色继承)。
+
+const innerSizeClass: Record<IconSize, string> = {
+  xs: 'size-3',
+  sm: 'size-4',
+  md: 'size-5',
+  lg: 'size-6',
+  xl: 'size-7',
+  '2xl': 'size-9',
+  '3xl': 'size-12',
+  // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- `inherit` 档跟随父级字号(em 单位),无法用 Tailwind token 表达。
+  inherit: 'size-[1em]',
+};
+
+/**
+ * Icon 图标容器 — 纯样式包裹层。
+ *
+ * 单一 children 通道(对齐 Mantine ThemeIcon),不再有 `icon` prop;
+ * `variant + color` 双轴(对齐 ADR 0021),不再有 `withBackground/shape/bgTone` 三轨。
+ * 7 档 size + spin/rotate + Slot + 装饰/非装饰无障碍。
+ *
+ * className / style 在所有分支均合并到外层根节点,完整透传。
+ */
+const Icon = React.forwardRef<HTMLSpanElement, IconProps>(
+  (
+    {
+      children,
+      variant = 'plain',
+      color = 'default',
+      size = 'md',
+      spin,
+      rotate,
+      asChild = false,
+      decorative = true,
+      className,
+      style,
+      ...rest
+    },
+    ref,
+  ) => {
+    const ariaProps: React.AriaAttributes & { role?: string } = decorative
+      ? { 'aria-hidden': true }
+      : { role: rest.role ?? 'img' };
+
+    const rotateStyle: React.CSSProperties | undefined = rotate
+      ? { transform: `rotate(${rotate}deg)` }
+      : undefined;
+    const mergedStyle: React.CSSProperties | undefined =
+      rotateStyle || style ? { ...rotateStyle, ...style } : undefined;
+
+    // 分支 C:Slot 模式 — 强制走 plain 形态,把所有 className / style / aria 合并到子元素根节点。
+    if (asChild) {
+      return (
+        <Slot
+          ref={ref}
+          className={cn(iconInnerVariants({ size, color, spin }), className)}
+          style={mergedStyle}
+          {...ariaProps}
+          {...rest}
+        >
+          {children}
+        </Slot>
+      );
+    }
+
+    // 分支 B:带背景容器(variant=circle/square)— 双 span 嵌套。
+    // 外层接 className / style / aria / ...rest 并提供背景 + color 前景色;
+    // inner span 只承担 svg size,color 从外层 `text-*` 继承(currentColor)。
+    if (variant !== 'plain') {
+      return (
+        <span
+          ref={ref}
+          className={cn(
+            iconContainerVariants({ variant, color, size }),
+            className,
+          )}
+          style={mergedStyle}
+          {...ariaProps}
+          {...rest}
+        >
+          <span
+            className={cn(
+              'inline-flex shrink-0 [&>svg]:size-full',
+              innerSizeClass[size],
+              spin && 'animate-spin',
+            )}
+          >
+            {children}
+          </span>
+        </span>
+      );
+    }
+
+    // 分支 A:plain — 单 span 包裹,size class 与 [&>svg]:size-full 直接生效。
+    if (children == null) return null;
+
+    return (
+      <span
+        ref={ref}
+        className={cn(iconInnerVariants({ size, color, spin }), className)}
+        style={mergedStyle}
+        {...ariaProps}
+        {...rest}
+      >
+        {children}
+      </span>
+    );
+  },
+);
+Icon.displayName = 'Icon';
+
+export { Icon };

package/src/components/image/image.meta.md

@@ -3,7 +3,7 @@ id: image
 name: Image
 displayName: 图片
 type: component
-category: foundation
+category: deprecated
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -27,31 +27,28 @@ package: '@teamix-evo/ui'
 ## Props
 
 <!-- auto:props:begin -->
-
-| 名称           | 类型              | 默认值 | 必填 | 说明                                                           |
-| -------------- | ----------------- | ------ | ---- | -------------------------------------------------------------- |
-| `src`          | `string`          | –      | ✓    | –                                                              |
-| `alt`          | `string`          | –      | ✓    | –                                                              |
-| `preview`      | `boolean`         | `true` | –    | 是否启用点击预览(antd `preview` 并集) — 点击后弹模态展示原图。 |
-| `fallback`     | `React.ReactNode` | –      | –    | 加载失败时显示的占位元素;不传则用默认 `ImageOff` 图标。        |
-| `placeholder`  | `React.ReactNode` | –      | –    | 加载中显示的占位 — 默认 Skeleton 占位与图片同尺寸。            |
-| `className`    | `string`          | –      | –    | 容器 className(图片本身用 `imgClassName`)。                    |
-| `imgClassName` | `string`          | –      | –    | 真实 `<img>` 的 className(尺寸 / 圆角 / object-fit)。          |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `src` | `string` | – | ✓ | – |
+| `alt` | `string` | – | ✓ | – |
+| `preview` | `boolean` | `true` | – | 是否启用点击预览(antd `preview` 并集) — 点击后弹模态展示原图。 |
+| `fallback` | `React.ReactNode` | – | – | 加载失败时显示的占位元素;不传则用默认 `ImageOff` 图标。 |
+| `placeholder` | `React.ReactNode` | – | – | 加载中显示的占位 — 默认 Skeleton 占位与图片同尺寸。 |
+| `className` | `string` | – | – | 容器 className(图片本身用 `imgClassName`)。 |
+| `imgClassName` | `string` | – | – | 真实 `<img>` 的 className(尺寸 / 圆角 / object-fit)。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add image` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry      | 类型      | 描述                                                                                              |
-| ---------- | --------- | ------------------------------------------------------------------------------------------------- |
-| `cn`       | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                                |
-| `dialog`   | component | 模态对话框 — Radix Dialog + antd Modal 并集(组合式 Header/Footer/Title/Description)               |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `dialog` | component | 模态对话框 — Radix Dialog + antd Modal 并集(组合式 Header/Footer/Title/Description,size sm/md/lg/xl 绑定 layout-dialog tokens,圆角 radius-dialog 16px,无 border) |
 | `skeleton` | component | 骨架屏 — shadcn pulse 单元素 + antd Avatar/Image/Button/Input/Paragraph 子家族,自动 motion-reduce |
 
 ### npm 依赖
@@ -61,7 +58,6 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/image/image.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Image } from './image';
 
 const meta: Meta<typeof Image> = {
-  title: '基础原语 · Foundation/Image',
+  title: '废弃 · Deprecated/Image',
   component: Image,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '图片 — 自动处理加载（Skeleton 占位）+ 失败（图标占位）+ 点击预览（Dialog 模态原图）。alt 必填（无障碍）。等价 antd Image。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n图片 — 自动处理加载（Skeleton 占位）+ 失败（图标占位）+ 点击预览（Dialog 模态原图）。alt 必填（无障碍）。等价 antd Image。',
       },
     },
   },

package/src/components/image/image.tsx

@@ -5,6 +5,7 @@ import { cn } from '@/utils/cn';
 import {
   Dialog,
   DialogContent,
+  DialogTitle,
   DialogTrigger,
 } from '@/components/dialog/dialog';
 import { Skeleton } from '@/components/skeleton/skeleton';
@@ -118,6 +119,7 @@ const Image = React.forwardRef<HTMLImageElement, ImageProps>(
           className="max-w-image-preview border-0 bg-transparent p-0 shadow-none"
           showClose={false}
         >
+          <DialogTitle className="sr-only">{alt}</DialogTitle>
           <div className="relative">
             <img
               src={src}

package/src/components/input/input.meta.md

@@ -2,7 +2,7 @@
 id: input
 name: Input
 type: component
-category: form
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 displayName: 输入框
@@ -10,42 +10,38 @@ displayName: 输入框
 
 # Input 输入框
 
-文本输入框 — shadcn 简洁版基底 + antd 的 `prefix / suffix / clearable / showCount / addonBefore / addonAfter / size`。
-单组件覆盖大部分表单输入场景,保持 forwardRef + 原生 `<input>` 透传。
+单行文本输入 — shadcn 简洁基底 + antd 并集中保留为内建逻辑能力的子集:`size` 三档(sm/md/lg,与 `Button` 同档)、`clearable` 一键清空、`showCount` + `maxLength` 字数计数、`error` / `aria-invalid` 错误态。
+
+> **2026-06 BREAKING**:`prefix` / `suffix` / `addonBefore` / `addonAfter` 4 个快捷 prop 已移除(ADR 0029)。"装饰类"前后缀(图标 / 文本 / 单位 / 协议头 / 内嵌按钮)统一改用同库独立组件 [`InputGroup`](../input-group/input-group.meta.md) 的复合插槽。`Textarea` 也已拆为 [独立 entry](../textarea/textarea.meta.md)。
 
 ## When to use
 
-- 任何文本输入(text / email / password / number / search / tel / url)
-- 配合 `prefix` 加搜索图标
-- 配合 `addonBefore="https://"` 输入域名
+- 任何单行文本输入(text / email / password / number / search / tel / url)
 - 配合 `clearable` 给搜索框一键清空
 - 配合 `showCount + maxLength` 给社媒发文限制字数
+- 配合 `error`(或 `aria-invalid`)给表单校验失败的字段加红边
 
 ## When NOT to use
 
-- 多行文本 → `Textarea`
-- 数字微调 → `Input type="number"` 已足够,需要步进按钮考虑独立 `InputNumber`
-- 选择类 → `Select` / `Combobox`
-- OTP 验证码 → `InputOTP`(v0.x)
+- 多行文本 → [`Textarea`](../textarea/textarea.meta.md)
+- 数字微调(含步进按钮) → `InputNumber`
+- 选择类输入 → `Select`
+- OTP 验证码 → `InputOTP`
+- 输入框前后需要图标 / 文本 / 协议头 / 单位 / 内嵌按钮 → [`InputGroup`](../input-group/input-group.meta.md)
 
 ## Props
 
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-
-| 名称           | 类型                        | 默认值      | 必填 | 说明                                                                      |
-| -------------- | --------------------------- | ----------- | ---- | ------------------------------------------------------------------------- |
-| `prefix`       | `React.ReactNode`           | –           | –    | 输入框前置图标 / 文本(antd `prefix` 并集)。                               |
-| `suffix`       | `React.ReactNode`           | –           | –    | 输入框后置图标 / 文本(antd `suffix` 并集)。                               |
-| `clearable`    | `boolean`                   | `false`     | –    | 显示清除按钮,有内容时点击清空(antd `allowClear` 并集)。                   |
-| `showCount`    | `boolean`                   | `false`     | –    | 显示字符计数(antd `showCount` 并集);需配合 `maxLength` 一起使用。         |
-| `addonBefore`  | `React.ReactNode`           | –           | –    | 输入框前置标签(antd `addonBefore` 并集),与外层组合形成 input-group。      |
-| `addonAfter`   | `React.ReactNode`           | –           | –    | 输入框后置标签(antd `addonAfter` 并集)。                                  |
-| `size`         | `'sm' \| 'default' \| 'lg'` | `"default"` | –    | 尺寸。                                                                    |
-| `value`        | `string`                    | –           | –    | 受控值,用于 clearable / showCount 的逻辑;未传时回退到 uncontrolled 行为。 |
-| `defaultValue` | `string`                    | –           | –    | uncontrolled 初始值。                                                     |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `clearable` | `boolean` | `false` | – | 显示清除按钮,有内容时点击清空(antd `allowClear` 并集)。 注:仅"快捷一键清空"逻辑保留为 Input 内建能力 — 复合的前后缀(图标 / 文本 / 按钮) 请用 `InputGroup` 系列。 |
+| `showCount` | `boolean` | `false` | – | 显示字符计数(antd `showCount` 并集);需配合 `maxLength` 一起使用。 |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'default'` | `"md"` | – | 尺寸三档,与 `Button` 同档:`sm`(24px) / `md`(32px,默认) / `lg`(36px)。 `"default"` 为兼容旧调用的别名,等价于 `"md"`,新代码请用 `"md"`。 |
+| `error` | `boolean` | `false` | – | 错误态(快捷开关),会同时设置 `aria-invalid`,渲染 destructive 边框 / ring。 也可以直接传 `aria-invalid` 原生属性达到同效果。 |
+| `value` | `string` | – | – | 受控值,用于 clearable / showCount 的逻辑;未传时回退到 uncontrolled 行为。 |
+| `defaultValue` | `string` | – | – | uncontrolled 初始值。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -53,14 +49,13 @@ displayName: 输入框
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add input` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -69,25 +64,35 @@ displayName: 输入框
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 > 透传所有 `<input>` 原生属性(`type` / `placeholder` / `name` / `id` / `aria-*` / `onChange` / ...)。
 
 ## AI 生成纪律
 
-- **`prefix/suffix` 与 `addonBefore/addonAfter` 区别**:`prefix/suffix` 在边框**内**,`addon*` 是独立按钮形态在边框**外**(常用于域名 / 单位 / 协议头)
-- **`showCount` 必须配 `maxLength`**:无 maxLength 时 showCount 不显示
-- **`clearable` 与 `suffix` 互斥位置**:有内容时 clear 优先,suffix 仍渲染但视觉权重需协调;**不要**同时塞太多 affix 内容
-- **type="password" 的可见切换**:用 `suffix={<Eye />}` + 状态控制 type 切换(组件不内置,业务侧做)
-- **`type="search"` 配合 `clearable`**:搜索框最佳搭档,提交按钮用 `addonAfter`
-- **不要硬编码颜色**:`bg-background` / `border-input` / `placeholder:text-muted-foreground` 都是 design token,**不要**改成 `bg-white`
+- **禁止使用已移除的 `prefix` / `suffix` / `addonBefore` / `addonAfter`**:这 4 个 prop 在 v0.x major 中**整段移除**,改用 `InputGroup` 复合插槽(见下方迁移示例)。
+- **`showCount` 必须配 `maxLength`**:无 maxLength 时 showCount 不渲染。
+- **`error` prop 自动设置 `aria-invalid`**:推荐传 `error`,也可直接传原生 `aria-invalid`;**不要**手动拼 `border-destructive`。
+- **size 档位严格三档**:`sm`(h-6/text-xs/24px)/ `md`(h-8/text-xs,默认/32px)/ `lg`(h-9/text-sm/36px);`"default"` 仅作向后兼容别名,**新代码**统一写 `"md"`,与 `Button` 同档便于同行混排。
+- **不要硬编码颜色**:`bg-background` / `border-input` / `placeholder:text-muted-foreground` 都是 design token,**不要**改成 `bg-white`。
+- **圆角走 `rounded-md`**(Tailwind v4 namespace token):uni-manager 2px / opentrek 6px;**禁止** `rounded-lg` / 自定义半径,确保与 Button / Select / DatePicker 同行视觉一致。
+
+## 用 InputGroup 替代 prefix / suffix / addon
+
+下表是从 `Input` 旧 4 个 prop 到 `InputGroup` 复合插槽的等价改写(ADR 0029 §Decision 2):
+
+| 旧写法                                               | 新写法                                                                                                                                                              |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<Input prefix={<Search />} />`                      | `<InputGroup><InputGroupAddon position="before" variant="icon"><Search /></InputGroupAddon><InputGroupInput /></InputGroup>`                                        |
+| `<Input suffix={<Mail />} />`                        | `<InputGroup><InputGroupInput /><InputGroupAddon position="after" variant="icon"><Mail /></InputGroupAddon></InputGroup>`                                           |
+| `<Input addonBefore="https://" addonAfter=".com" />` | `<InputGroup><InputGroupAddon position="before">https://</InputGroupAddon><InputGroupInput /><InputGroupAddon position="after">.com</InputGroupAddon></InputGroup>` |
+| `<Input prefix="¥" suffix="USD" />`                  | `<InputGroup><InputGroupAddon position="before">¥</InputGroupAddon><InputGroupInput /><InputGroupAddon position="after">USD</InputGroupAddon></InputGroup>`         |
+| `<Input addonAfter={<Button>搜索</Button>} />`       | `<InputGroup><InputGroupInput /><InputGroupAddon position="after" variant="button"><Button variant="ghost">搜索</Button></InputGroupAddon></InputGroup>`            |
 
 ## Examples
 
 ```tsx
 import { Input } from '@/components/ui/input';
-import { Search, Mail } from 'lucide-react';
 
 // 基础
 <Input placeholder="请输入..." />
@@ -96,19 +101,15 @@ import { Search, Mail } from 'lucide-react';
 const [v, setV] = React.useState('');
 <Input value={v} onChange={(e) => setV(e.target.value)} />
 
-// 前置图标
-<Input prefix={<Search />} placeholder="搜索..." />
-
 // 可清除 + 字数统计
 <Input clearable showCount maxLength={140} placeholder="动态..." />
 
-// 域名 input(addon-before)
-<Input addonBefore="https://" addonAfter=".com" defaultValue="teamix-evo" />
-
-// 邮箱 + suffix
-<Input type="email" suffix={<Mail />} placeholder="you@example.com" />
+// 错误态
+<Input error placeholder="必填" />
 
 // 尺寸
 <Input size="sm" placeholder="紧凑" />
 <Input size="lg" placeholder="宽松" />
 ```
+
+需要图标 / 协议头 / 内嵌按钮 → 见 [`InputGroup`](../input-group/input-group.meta.md) 与 Storybook `WithInputGroup` 示例。

package/src/components/input/input.stories.tsx

@@ -1,22 +1,27 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
-import { Mail, Search } from 'lucide-react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Search } from 'lucide-react';
 import { Input } from './input';
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupInput,
+} from '@/components/input-group/input-group';
 
 const meta: Meta<typeof Input> = {
-  title: '表单与输入 · Form/Input',
+  title: '数据录入 · Data Entry/Input',
   component: Input,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '输入框 — 文本 / 邮箱 / 密码 / 搜索等单行输入。shadcn 原生 `<input>` 风格 + antd 扩展：`size` 三档、`prefix` / `suffix` 前后缀、`addonBefore` / `addonAfter` 外联组、`clearable` 一键清空、`showCount` + `maxLength` 字数统计。',
+          '输入框 — shadcn 简洁基底 + antd 并集中保留为内建逻辑能力的:`size` 三档(sm/md/lg,与 `Button` 同档)、`clearable` 一键清空、`showCount` + `maxLength` 字数统计、`error` / `aria-invalid` 错误态。**前后缀 / 单位 / 协议头 / 内嵌按钮**等"装饰类"形态请用同库 `InputGroup` 复合插槽(见下方 `WithInputGroup` 示例)— 单一职责更清晰,与 shadcn 2025-10 拆分对齐(ADR 0029)。',
       },
     },
   },
   argTypes: {
-    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
+    size: { control: 'inline-radio', options: ['sm', 'md', 'lg'] },
     type: {
       control: 'select',
       options: ['text', 'email', 'password', 'search', 'tel', 'url'],
@@ -24,15 +29,17 @@ const meta: Meta<typeof Input> = {
     clearable: { control: 'boolean' },
     showCount: { control: 'boolean' },
     disabled: { control: 'boolean' },
+    error: { control: 'boolean' },
     placeholder: { control: 'text' },
     maxLength: { control: 'number' },
   },
   args: {
-    size: 'default',
+    size: 'md',
     type: 'text',
     clearable: false,
     showCount: false,
     disabled: false,
+    error: false,
     placeholder: '请输入...',
   },
   decorators: [
@@ -53,35 +60,9 @@ export const Sizes: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <div className="flex flex-col gap-3">
-      <Input size="sm" placeholder="Small" />
-      <Input size="default" placeholder="Default" />
-      <Input size="lg" placeholder="Large" />
-    </div>
-  ),
-};
-
-export const PrefixSuffix: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex flex-col gap-3">
-      <Input prefix={<Search />} placeholder="搜索..." />
-      <Input type="email" suffix={<Mail />} placeholder="you@example.com" />
-      <Input prefix="¥" suffix="USD" placeholder="0.00" />
-    </div>
-  ),
-};
-
-export const Addon: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex flex-col gap-3">
-      <Input
-        addonBefore="https://"
-        defaultValue="teamix-evo"
-        addonAfter=".com"
-      />
-      <Input addonBefore="@" placeholder="username" />
-      <Input addonAfter="kg" defaultValue="42" />
+      <Input size="sm" placeholder="Small (h-6 / text-xs / 24px)" />
+      <Input size="md" placeholder="Medium (h-8 / text-xs / 32px)" />
+      <Input size="lg" placeholder="Large (h-9 / text-sm / 36px)" />
     </div>
   ),
 };
@@ -106,6 +87,16 @@ export const ShowCount: Story = {
   render: () => <Input showCount maxLength={140} placeholder="发布动态" />,
 };
 
+export const Error: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Input error placeholder="必填" />
+      <Input error defaultValue="非法值" />
+    </div>
+  ),
+};
+
 export const Disabled: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
@@ -115,3 +106,39 @@ export const Disabled: Story = {
     </div>
   ),
 };
+
+/**
+ * 想加图标 / 单位 / 协议头?用 `InputGroup` 复合插槽 — 不再用已废弃的
+ * `prefix` / `suffix` / `addonBefore` / `addonAfter` 快捷 prop(ADR 0029)。
+ *
+ * 详细演示与 API 见 `数据录入 · Data Entry/InputGroup` 故事集。
+ */
+export const WithInputGroup: Story = {
+  name: '配合 InputGroup(替代旧 prefix/suffix/addon)',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-80 flex-col gap-3">
+      {/* 图标前缀(替代旧 prefix={<Search />}) */}
+      <InputGroup>
+        <InputGroupAddon position="before" variant="icon">
+          <Search className="size-4" />
+        </InputGroupAddon>
+        <InputGroupInput placeholder="搜索..." />
+      </InputGroup>
+
+      {/* URL 协议头/后缀(替代旧 addonBefore="https://" addonAfter=".com") */}
+      <InputGroup>
+        <InputGroupAddon position="before">https://</InputGroupAddon>
+        <InputGroupInput defaultValue="example" />
+        <InputGroupAddon position="after">.com</InputGroupAddon>
+      </InputGroup>
+
+      {/* 金额/单位(替代旧 prefix="¥" suffix="USD") */}
+      <InputGroup>
+        <InputGroupAddon position="before">¥</InputGroupAddon>
+        <InputGroupInput type="number" defaultValue={199} />
+        <InputGroupAddon position="after">/ 月</InputGroupAddon>
+      </InputGroup>
+    </div>
+  ),
+};