@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/icon/DEVELOPMENT.md

@@ -0,0 +1,809 @@
+# Icon 组件研发文档
+
+> ⚠️ **当前 API 状态**:`children` / `variant` / **`color`** / `size` / `spin` / `rotate` / `asChild` / `decorative`。
+> `tone` 该 prop 名在 v0.1 结束后二次回退为 `color`(详见**附录 C**、[ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md))。本文档为演进档案 —— 实现以 `icon.tsx` / `icon.stories.tsx` / `icon.meta.md` 为准。
+
+> 本文档为 `@teamix-evo/ui` Icon 组件的完整研发分析,基于 cloud-design 中 `Icon` 的能力承接(`@alifd/next` Icon + `createFromIconfontCN`),按照 ui 库第零条准则(能力做并集,理念跟 design,工程跟 shadcn)重新设计实现。
+
+> ⚠️ **本组件存在的两个核心理由**：① **背景色容器** — 圆形/方形 + 彩色背景的 icon 容器,lucide 直用每处都得自拼 div+bg+radius+居中,极易视觉漂移;② **多 icon 源统一出入口** — 默认 `lucide-react`,预留 iconfont 与未来其他 icon set 的工厂接入点,API 一次稳定,源可换。**仅 size + color 不必包**(shadcn 工程理念就是 lucide + className 直用),不要把本组件当作 lucide 的强制中转。
+
+---
+
+## 一、源头分析 — Icon(cloud-design)
+
+### 1.1 原始组件定位
+
+cloud-design 的 Icon 直接转出 `@alifd/next` 的 Icon,在阿里云控制台生态承担两类职责：
+
+| 职责       | 内容                                                                                   | 原始实现位置                            |
+| ---------- | -------------------------------------------------------------------------------------- | --------------------------------------- |
+| 内置图标   | 56 个语义化图标(success / warning / error / loading / smile 等) + xconsole 扩展集      | `@alifd/next` Icon 内置 type 字典       |
+| 自定义源   | iconfont CN 脚本注入,通过 `createFromIconfontCN({ scriptUrl })` 拿到一个新的 Icon 组件 | `@alifd/next` Icon.createFromIconfontCN |
+| 尺寸语义化 | 9 档尺寸 + inherit + number(自由像素值)                                                | size prop                               |
+| 自定义样式 | style.color / className 自由透传(图标本质是字体)                                       | style/className 透传                    |
+| 无障碍     | 文档约束:装饰性走 `aria-hidden`,按钮型走 `role="button" + aria-label`                  | 文档约束(无运行时强制)                  |
+
+### 1.2 原始 Props 清单
+
+```typescript
+type CloudDesignIconProps = {
+  type: string; // 必填:内置图标名或 createFromIconfontCN 返回组件后的扩展 type
+  size?:
+    | 'xxs' | 'xs' | 'small' | 'medium' | 'large'
+    | 'xl' | 'xxl' | 'xxxl' | 'inherit' | number;
+  // 其它 HTML 属性透传(style / className / role / aria-* ...)
+};
+
+// 工厂方法
+Icon.createFromIconfontCN({ scriptUrl: string }): React.ComponentType<{ type: string; size?: ... }>;
+```
+
+### 1.3 原始依赖与生态
+
+| 依赖                 | 来源              | 作用                                |
+| -------------------- | ----------------- | ----------------------------------- |
+| `@alifd/next` Icon   | next 内置         | 渲染层 + 内置 svg 字典              |
+| iconfont.cn / 主题包 | 远程 / npm 主题包 | 扩展 type 字典(svg symbol 注入 DOM) |
+| Fusion 主题包变量    | 主题 npm          | 控制 type 与 svg 之间的映射         |
+
+> cloud-design 的 Icon 与 Fusion 主题包深度耦合 —— 每个主题包都内嵌一份 iconfont 地址,变换主题即变换内置 type 字典,这与 teamix-evo "源码注入 + 静态 lucide" 的理念**根本不同**。
+
+---
+
+## 二、第零条准则对照表(三层对齐)
+
+### 2.1 能力对标 — shadcn ∪ antd ∪ cloud-design 并集
+
+> shadcn-ui 没有 Icon wrapper(直接 `import { Smile } from 'lucide-react'` 用),`@ant-design/icons` 提供 wrapper(`<SmileOutlined />` + `<Icon component={Svg} />`),cloud-design 提供 Icon + iconfont 工厂。本组件落点:**承接 cloud-design 的"icon 容器 + 多源工厂"理念,采用 antd 的 `spin` / `rotate` 类语义化 prop,工程对齐 shadcn(lucide 单源 + cva + Slot)**。
+
+| 能力维度             | shadcn 提供                                            | antd 提供(@ant-design/icons)                     | cloud-design 提供                                                        | 本组件实现                                                                                            |
+| -------------------- | ------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| icon source          | 直接 `import { Smile } from 'lucide-react'`,无 wrapper | `<SmileOutlined />` + `<Icon component={Svg} />` | iconfont type + `createFromIconfontCN`                                   | **多源工厂**:默认 lucide(`icon` prop 接 `LucideIcon`)+ `createIconfontIcon({ scriptUrl })` 工厂(v0.2) |
+| **背景色容器**(核心) | ❌                                                     | ❌                                               | ✅ `iconBackgroundType` + `iconBackgroundColor`                          | ✅ `withBackground` + `shape: circle/square` + `bgTone: neutral/primary/destructive/success/warning`  |
+| size 档位            | className `size-4 / size-5 / size-6` 自定              | `fontSize` 数值                                  | `xxs / xs / small / medium / large / xl / xxl / xxxl / inherit / number` | 5 档枚举 `xs / sm / md / lg / xl` + `inherit`(对齐 cloud-design 5 档主流值,放弃过度细分的 xxs/xxxl)   |
+| 语义配色             | 无统一 wrapper(自由 className)                         | 无                                               | `style.color` 自由                                                       | `tone: default / muted / primary / destructive / success / warning`(走 `@teamix-evo/tokens` 语义色)   |
+| spin                 | ❌(自己写 `animate-spin`)                              | ✅ `spin`                                        | ❌(loading 是单独 type)                                                  | ✅ `spin`                                                                                             |
+| rotate               | ❌(自己写 `style.transform`)                           | ✅ `rotate={number}`                             | ❌                                                                       | ✅ `rotate`                                                                                           |
+| asChild (Slot)       | ✅                                                     | ❌                                               | ❌                                                                       | ✅                                                                                                    |
+| 无障碍               | 自己写 `aria-hidden`                                   | 自己写                                           | 文档约束(运行时不强制)                                                   | `decorative` 默认 true 自动 `aria-hidden`;非装饰必须 `aria-label`                                     |
+| 自定义 SVG           | 自由 import + className                                | `<Icon component={Svg} />`                       | createFromIconfontCN                                                     | 透传 children(任意 ReactNode 都走 children 通道)                                                      |
+| iconfont 扩展        | ❌                                                     | ❌                                               | ✅                                                                       | **v0.2 接入,API 已稳定**(`createIconfontIcon({ scriptUrl })`)                                         |
+
+简记:**核心是"带背景的多源 icon 容器";size/tone/spin/rotate 顺带统一;命名/工程对齐 shadcn;首发源只锁 lucide-react,iconfont 工厂第二批落地,但 API 在 v0.1 就稳定**。
+
+### 2.2 设计理念 — 跟 `@teamix-evo/tokens` OpenTrek 体系
+
+- **配色**走 semantic tokens:
+  - inner tone:`text-current` / `text-muted-foreground` / `text-primary` / `text-destructive` / `text-success` / `text-warning`
+  - container bgTone:`bg-muted text-foreground` / `bg-primary/10 text-primary` / `bg-destructive/10 text-destructive` / `bg-success/10 text-success` / `bg-warning/10 text-warning`
+  - **不照搬** cloud-design 的 `iconColor: 'blue' | 'green' | 'orange' | 'red' | 'yellow'` 原色枚举,改走 OpenTrek 语义色
+- **尺寸**走 4px 倍数 Tailwind size 体系:
+  - inner:`size-3 / size-3.5 / size-4 / size-5 / size-6` 即 12 / 14 / 16 / 20 / 24px
+  - container:`size-5 / size-6 / size-8 / size-10 / size-12` 即 20 / 24 / 32 / 40 / 48px(inner × 1.67~2.0)
+- **圆角**走五档:`rounded-full`(circle) / `rounded-md`(square,对齐 OpenTrek 卡片圆角)
+- **动效**:spin 走 `animate-spin`(Tailwind 1s 线性循环,与 spinner 组件一致),rotate 走 inline `transform`
+- **不引入运行时主题机制**,不参照 antd Icon 的 fontSize 数值制,也不参照 cloud-design 主题包的 iconfont 映射
+
+### 2.3 代码实现 — 跟 shadcn
+
+- **文件结构**:`src/components/icon/icon.tsx` + `.meta.md` + `.stories.tsx`
+- **cva 范式**:inner 与 container 各一份 cva(职责分离,不在一份 cva 里塞 9 个 variant)
+- **forwardRef**:`Icon` 用 `React.forwardRef<HTMLSpanElement, IconProps>`
+- **假路径 import**:`@/utils/cn`
+- **TypeScript strict**:每个 prop 有 JSDoc + `@default`,供 `pnpm gen:meta` 自动生成 props 表
+- **Tailwind**:全部 utility,**不写一行 less/scss**
+- **Slot**:`asChild=true` 时容器从 `span` 切到 `@radix-ui/react-slot`
+- **icon 单源**:遵守 ESLint `teamix-evo/icon-from-lucide`(本组件就是该规则的官方收口出口),组件内部仅 import lucide-react 类型;消费方传入的也只接受 `LucideIcon` 与任意 ReactNode
+
+---
+
+## 三、组件结构设计
+
+### 3.1 职责拆分(双层结构,而非复合组件)
+
+Icon 不像 PageHeader / Card / Dialog 那样需要复合组件 —— 它本质是一个"内层 svg + 可选外层背景容器"的双层结构,**单一组件 + 两个 cva** 即可表达,**不导出 IconContainer / IconInner 等子组件**(避免 API 表面积膨胀)。
+
+```
+Icon
+├── (withBackground=false,默认)
+│   └── IconCmp (lucide 组件 / children)  ← 应用 iconInnerVariants
+│
+└── (withBackground=true)
+    └── span [iconContainerVariants]
+        └── IconCmp ← 应用 iconInnerVariants(尺寸自动缩到合适比例)
+```
+
+### 3.2 双 cva 职责边界
+
+| cva                     | 应用对象                | 控制维度                    | 说明                                                                             |
+| ----------------------- | ----------------------- | --------------------------- | -------------------------------------------------------------------------------- |
+| `iconInnerVariants`     | inner svg / lucide 组件 | `size` / `tone` / `spin`    | 不论是否有背景容器都会应用                                                       |
+| `iconContainerVariants` | 外层背景 span           | `size` / `shape` / `bgTone` | 仅 `withBackground=true` 时启用;容器 size 与 inner size 一一映射(xs↔xs,..,xl↔xl) |
+
+> **不让消费方分别控 inner size / container size** —— 用户只传一个 `size`,内外尺寸联动,符合 P3 Predictability(同样的 prop 给同样的视觉强度)。
+
+---
+
+## 四、Props 接口设计
+
+```typescript
+import type { LucideIcon } from 'lucide-react';
+
+export interface IconProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'>,
+    VariantProps<typeof iconInnerVariants> {
+  /**
+   * 直接传入 lucide 组件(推荐写法)。与 children 互斥;同时存在时 children 优先。
+   * @example <Icon icon={Smile} />
+   */
+  icon?: LucideIcon;
+
+  /**
+   * 任意 ReactNode 透传 — 用于自定义 SVG / iconfont 工厂返回的组件 / asChild 场景。
+   */
+  children?: React.ReactNode;
+
+  /**
+   * 尺寸 — 5 档枚举 + inherit。inherit 走 `1em`,跟随父级字号。
+   * @default "md"
+   */
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'inherit';
+
+  /**
+   * 内层 icon 配色 — 走 OpenTrek 语义色;`default` = currentColor 跟随父级。
+   * @default "default"
+   */
+  tone?:
+    | 'default'
+    | 'muted'
+    | 'primary'
+    | 'destructive'
+    | 'success'
+    | 'warning';
+
+  /**
+   * 旋转动效 — 与 antd Icon `spin` 对齐,Tailwind `animate-spin` 实现。
+   * @default false
+   */
+  spin?: boolean;
+
+  /**
+   * 静态旋转角度(度数)— 与 antd Icon `rotate` 对齐,通过 inline transform 实现。
+   * 与 `spin` 同时使用时 `spin` 的动效优先,但 transform 起点会受影响,**不建议同时使用**。
+   * @example rotate={90}
+   */
+  rotate?: number;
+
+  /**
+   * Slot 模式 — 把渲染目标交给消费方提供的子元素(如 `<a>` / `<button>` / 自定义组件)。
+   * 与 `icon` / `withBackground` 互斥(开启时这两个 prop 被忽略)。
+   * @default false
+   */
+  asChild?: boolean;
+
+  /**
+   * 装饰性图标(默认 true,自动 `aria-hidden="true"`)。
+   * 当图标承载语义信息时设为 false,**必须**同时提供 `aria-label` 或被 `<button aria-label>` 包裹。
+   * @default true
+   */
+  decorative?: boolean;
+
+  /**
+   * 启用背景容器。开启后外层 span 应用 shape + bgTone,inner svg 自动缩到合适比例。
+   * @default false
+   */
+  withBackground?: boolean;
+
+  /**
+   * 容器形状(仅 `withBackground=true` 生效)。
+   * @default "circle"
+   */
+  shape?: 'circle' | 'square';
+
+  /**
+   * 容器背景配色(仅 `withBackground=true` 生效)。
+   * @default "neutral"
+   */
+  bgTone?: 'neutral' | 'primary' | 'destructive' | 'success' | 'warning';
+}
+```
+
+### Props 设计说明
+
+| Prop                               | 设计取舍                                                                                                                                                  |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `icon` vs `children`               | 推荐 `icon`(类型受 `LucideIcon` 约束,IDE 提示更精准);`children` 兜底自定义 SVG / iconfont 工厂                                                            |
+| `size` 档位                        | 放弃 cloud-design 的 9 档(xxs..xxxl),收敛到 5 档 + inherit。理由:OpenTrek 实际只用得到 4~5 档,过细的 xxs/xxxl 反而引发"先选什么"的决策成本(P4 Efficiency) |
+| `tone` 默认值                      | `default` = `text-current`,跟随父级 — 90% 场景不需要单独设色,跟父容器的 text 色即可                                                                       |
+| `pixelSize`                        | **不提供**。理由:开了像素自由就破坏 token 纪律(P3),消费方真有特殊像素诉求,直接传 `className="size-[Xpx]"` 走 lint warn 路径                               |
+| `decorative` 默认 true             | 与 cloud-design 文档约束一致(默认装饰性);非装饰场景必须显式声明,降低无障碍漏检概率                                                                        |
+| `asChild` 与 `withBackground` 互斥 | 背景容器需要外层 span 渲染,Slot 会替换该 span,语义冲突 — 强制二选一                                                                                       |
+
+---
+
+## 五、渲染结构设计
+
+### 5.1 三种渲染分支
+
+```tsx
+// 分支 A:withBackground=false,asChild=false(默认)
+// 直接渲染 IconCmp,应用 inner variants + aria + style
+<IconCmp
+  className={cn(iconInnerVariants({ size, tone, spin }), className)}
+  style={{ ...(rotate ? { transform: `rotate(${rotate}deg)` } : null), ...style }}
+  {...ariaProps}
+  {...rest}
+/>
+
+// 分支 B:withBackground=true,asChild=false
+// 外层 span 提供背景容器,inner 走 svg 默认尺寸缩放
+<span
+  className={cn(iconContainerVariants({ size, shape, bgTone }), className)}
+  {...ariaProps}
+  {...rest}
+>
+  <IconCmp
+    className={cn(iconInnerVariants({ size, tone: bgToneToInnerTone(bgTone), spin }))}
+    style={rotate ? { transform: `rotate(${rotate}deg)` } : undefined}
+  />
+</span>
+
+// 分支 C:asChild=true(忽略 withBackground)
+<Slot
+  className={cn(iconInnerVariants({ size, tone, spin }), className)}
+  style={{ ...(rotate ? { transform: `rotate(${rotate}deg)` } : null), ...style }}
+  {...ariaProps}
+  {...rest}
+/>
+```
+
+### 5.2 inner svg 在背景容器内的尺寸映射
+
+容器尺寸固定后,inner svg 应该缩到容器 50%~60% 视觉舒适。建议 `iconInnerVariants` 的 size 在容器内统一 hard-code 为容器 size **降一档**(如容器 `md`=32px → inner 走 `sm`=14px;容器 `lg`=40px → inner 走 `md`=16px)。
+
+实现细节(组件内部小工具):
+
+```typescript
+const innerSizeInContainer: Record<
+  NonNullable<IconProps['size']>,
+  NonNullable<IconProps['size']>
+> = {
+  xs: 'xs',
+  sm: 'xs',
+  md: 'sm',
+  lg: 'md',
+  xl: 'lg',
+  inherit: 'inherit',
+};
+```
+
+### 5.3 bgTone 与 inner tone 的语义联动
+
+开启背景容器后,inner tone 强制由 bgTone 推导(`bg-primary/10` 配 `text-primary`,语义已锁定),**忽略消费方传入的 `tone`** —— 避免出现 `bgTone="primary" tone="destructive"` 这种语义打架。
+
+```typescript
+const bgToneToInnerTone: Record<
+  NonNullable<IconProps['bgTone']>,
+  NonNullable<IconProps['tone']>
+> = {
+  neutral: 'default',
+  primary: 'primary',
+  destructive: 'destructive',
+  success: 'success',
+  warning: 'warning',
+};
+```
+
+---
+
+## 六、cva 配置完整草稿
+
+```typescript
+import { cva, type VariantProps } from 'class-variance-authority';
+
+// 内层:实际渲染的 svg/icon 组件本身的尺寸 + 着色 + 旋转
+export const iconInnerVariants = cva('inline-block shrink-0', {
+  variants: {
+    size: {
+      xs: 'size-3', // 12px
+      sm: 'size-3.5', // 14px
+      md: 'size-4', // 16px(默认)
+      lg: 'size-5', // 20px
+      xl: 'size-6', // 24px
+      inherit: 'size-[1em]', // 跟随父级字号
+    },
+    tone: {
+      default: 'text-current',
+      muted: 'text-muted-foreground',
+      primary: 'text-primary',
+      destructive: 'text-destructive',
+      success: 'text-success', // tokens 暂缺时 fallback 到 currentColor,见 ADR 0008
+      warning: 'text-warning',
+    },
+    spin: { true: 'animate-spin' },
+  },
+  defaultVariants: { size: 'md', tone: 'default' },
+});
+
+// 外层:背景容器 — 仅 withBackground=true 时启用
+export const iconContainerVariants = cva(
+  'inline-flex items-center justify-center shrink-0',
+  {
+    variants: {
+      shape: {
+        circle: 'rounded-full',
+        square: 'rounded-md',
+      },
+      bgTone: {
+        neutral: 'bg-muted text-foreground',
+        primary: 'bg-primary/10 text-primary',
+        destructive: 'bg-destructive/10 text-destructive',
+        success: 'bg-success/10 text-success',
+        warning: 'bg-warning/10 text-warning',
+      },
+      size: {
+        xs: 'size-5', // 20px
+        sm: 'size-6', // 24px
+        md: 'size-8', // 32px(默认)
+        lg: 'size-10', // 40px
+        xl: 'size-12', // 48px
+        inherit: 'size-[1.75em]',
+      },
+    },
+    defaultVariants: { shape: 'circle', bgTone: 'neutral', size: 'md' },
+  },
+);
+
+export type IconInnerVariants = VariantProps<typeof iconInnerVariants>;
+export type IconContainerVariants = VariantProps<typeof iconContainerVariants>;
+```
+
+> `success` / `warning` 的 token(`--color-success` / `--color-warning`)当前在 `@teamix-evo/tokens` OpenTrek variant 内尚未定义 —— **不阻塞本次交付**,运行时未定义时 Tailwind 解析失败 fallback 到 currentColor;由 [ADR 0008](../../../../../docs/adr/0008-eslint-visual-rules-warn-baseline.md) 标注的 token 补齐路径修复。
+
+---
+
+## 七、组件实现草稿
+
+```tsx
+// packages/ui/src/components/icon/icon.tsx
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import type { LucideIcon } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+import {
+  iconInnerVariants,
+  iconContainerVariants,
+  type IconInnerVariants,
+} from './icon.variants'; // 或直接放在 icon.tsx 顶部
+
+const innerSizeInContainer = {
+  xs: 'xs',
+  sm: 'xs',
+  md: 'sm',
+  lg: 'md',
+  xl: 'lg',
+  inherit: 'inherit',
+} as const;
+
+const bgToneToInnerTone = {
+  neutral: 'default',
+  primary: 'primary',
+  destructive: 'destructive',
+  success: 'success',
+  warning: 'warning',
+} as const;
+
+export interface IconProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'>,
+    IconInnerVariants {
+  icon?: LucideIcon;
+  children?: React.ReactNode;
+  rotate?: number;
+  asChild?: boolean;
+  decorative?: boolean;
+  withBackground?: boolean;
+  shape?: 'circle' | 'square';
+  bgTone?: 'neutral' | 'primary' | 'destructive' | 'success' | 'warning';
+}
+
+export const Icon = React.forwardRef<HTMLSpanElement, IconProps>(
+  (
+    {
+      icon: IconCmp,
+      children,
+      size = 'md',
+      tone = 'default',
+      spin,
+      rotate,
+      asChild,
+      decorative = true,
+      withBackground,
+      shape = 'circle',
+      bgTone = 'neutral',
+      className,
+      style,
+      ...rest
+    },
+    ref,
+  ) => {
+    const ariaProps: React.AriaAttributes & { role?: string } = decorative
+      ? { 'aria-hidden': true }
+      : { role: rest.role ?? 'img' };
+
+    const rotateStyle = rotate
+      ? { transform: `rotate(${rotate}deg)` }
+      : undefined;
+    const mergedStyle = { ...rotateStyle, ...style };
+
+    // 分支 C:Slot 模式
+    if (asChild) {
+      return (
+        <Slot
+          ref={ref}
+          className={cn(iconInnerVariants({ size, tone, spin }), className)}
+          style={mergedStyle}
+          {...ariaProps}
+          {...rest}
+        >
+          {children}
+        </Slot>
+      );
+    }
+
+    // 分支 B:背景容器
+    if (withBackground) {
+      const innerSize = innerSizeInContainer[size];
+      const innerTone = bgToneToInnerTone[bgTone];
+      return (
+        <span
+          ref={ref}
+          className={cn(
+            iconContainerVariants({ size, shape, bgTone }),
+            className,
+          )}
+          {...ariaProps}
+          {...rest}
+        >
+          {children ? (
+            <span
+              className={cn(
+                iconInnerVariants({ size: innerSize, tone: innerTone, spin }),
+              )}
+              style={rotateStyle}
+            >
+              {children}
+            </span>
+          ) : IconCmp ? (
+            <IconCmp
+              className={cn(
+                iconInnerVariants({ size: innerSize, tone: innerTone, spin }),
+              )}
+              style={rotateStyle}
+            />
+          ) : null}
+        </span>
+      );
+    }
+
+    // 分支 A:默认(直接渲染 inner)
+    if (children) {
+      return (
+        <span
+          ref={ref}
+          className={cn(iconInnerVariants({ size, tone, spin }), className)}
+          style={mergedStyle}
+          {...ariaProps}
+          {...rest}
+        >
+          {children}
+        </span>
+      );
+    }
+
+    if (IconCmp) {
+      return (
+        <IconCmp
+          ref={ref as never}
+          className={cn(iconInnerVariants({ size, tone, spin }), className)}
+          style={mergedStyle}
+          {...ariaProps}
+          {...rest}
+        />
+      );
+    }
+
+    return null;
+  },
+);
+Icon.displayName = 'Icon';
+```
+
+### 实现要点
+
+- **lucide 组件直接接受 `className` / `style` / `ref`**(它们都是 React.forwardRef SVG),所以默认分支可以零包裹直出,避免无谓 span 嵌套
+- **children 走 children,icon 走 icon**:不再支持"两者都传"(同时存在时 children 优先,但开发时建议 lint 报警)
+- **withBackground + children** 也支持(自定义 SVG 也能套背景容器)
+- **asChild + Slot**:`@radix-ui/react-slot` 会把所有 className/style/事件 merge 到子元素根节点,适合给 `<a><Icon icon={...}/></a>` 这类容器加图标样式
+
+---
+
+## 八、AI 生成纪律
+
+### 8.1 硬约束(写代码时禁止越界)
+
+- **禁止内联 `<svg>`** —— 用 lucide 现成图标(`import { Smile } from 'lucide-react'`),特殊场景才走 children 通道传自定义 svg
+- **禁止从 `@ant-design/icons` / `@alifd/next` icon 引入** —— 由 [`@teamix-evo/eslint-config`](../../../../eslint-config/) 的 `teamix-evo/icon-from-lucide` 规则强制
+- **禁止给 Icon 加 `pixelSize` / arbitrary `size-[Xpx]`** —— 用 5 档枚举 size,真有特殊像素诉求走 lint warn 路径用 `className`,且每处需 review
+- **禁止颜色字面量** —— `style={{ color: '#1DC11D' }}` 是 cloud-design 老写法,现在走 `tone` 枚举或父级 currentColor
+- **禁止给 Icon 加点击事件后忘记加 `decorative={false}` + `aria-label`** —— 装饰性图标不应承担交互,要交互必须语义化
+
+### 8.2 推荐范式
+
+- **基础用法**:`<Icon icon={Smile} />`(默认装饰性,默认 md size,跟随父色)
+- **状态色**:`<Icon icon={CheckCircle2} tone="success" size="lg" />`
+- **背景容器**:`<Icon icon={AlertTriangle} withBackground bgTone="warning" shape="circle" size="lg" />`
+- **加载**:`<Icon icon={Loader2} spin tone="muted" />`(注意:常规 loading 优先用 [Spinner](../spinner/spinner.tsx) 组件,Spinner 内部已封装好 `role="status"` + `sr-only` 文案)
+- **可点击**:`<button aria-label="删除"><Icon icon={Trash2} decorative /></button>`(图标装饰性,语义靠 button)
+- **Slot 包裹**:`<Icon asChild size="lg" tone="primary"><a href="..."><MyCustomLogo /></a></Icon>`
+
+### 8.3 反例
+
+- ❌ `<Icon icon={Smile} pixelSize={17} />` — 不该开像素自由
+- ❌ `<Icon icon={Trash2} onClick={...} />` — 装饰性图标不应承担交互;要交互包 `<button>`
+- ❌ `<Icon icon={Loader2} spin rotate={45} />` — spin 与 rotate 同用语义模糊,选一个
+- ❌ `<Icon withBackground bgTone="primary" tone="destructive" />` — 背景与内层 tone 打架(实现层会忽略 tone,但代码意图就是错的)
+- ❌ `import { Icon } from '@/components/icon'; <Icon icon={SmileOutlined as any} />` — antd icon 不是 LucideIcon
+- ❌ 全屏 loading 用 `<Icon icon={Loader2} spin size="xl" />` — 用 `<Spinner size="xl" />`,后者带读屏文案
+
+---
+
+## 九、registryDependencies 与 npm 依赖
+
+### 9.1 同库依赖
+
+| Entry | 类型 | 作用                                    |
+| ----- | ---- | --------------------------------------- |
+| `cn`  | util | className 合并(`clsx + tailwind-merge`) |
+
+> `lucide-react` 的具体图标**不**列入 registryDependencies —— 消费方按需 import,本组件不绑定任何具体图标。
+
+### 9.2 npm 依赖
+
+```json
+{
+  "@radix-ui/react-slot": "^1.1.0",
+  "class-variance-authority": "^0.7.0",
+  "lucide-react": "^0.460.0"
+}
+```
+
+### 9.3 manifest.json entry 草稿
+
+```json
+{
+  "id": "icon",
+  "name": "Icon",
+  "type": "component",
+  "description": "图标容器 — 基于 lucide-react 的统一封装。5 档尺寸 + 6 档语义配色 + spin/rotate + Slot + 背景容器(circle/square × 5 档 bgTone) + 装饰/非装饰无障碍。承接 cloud-design Icon 的尺寸语义与 iconBackgroundType/Color 能力,iconfont 工厂 v0.2 接入但 API 已稳定",
+  "files": [
+    {
+      "source": "src/components/icon/icon.tsx",
+      "targetAlias": "components",
+      "targetName": "icon.tsx"
+    }
+  ],
+  "meta": "src/components/icon/icon.meta.md",
+  "registryDependencies": ["cn"],
+  "dependencies": {
+    "@radix-ui/react-slot": "^1.1.0",
+    "class-variance-authority": "^0.7.0",
+    "lucide-react": "^0.460.0"
+  },
+  "updateStrategy": "frozen"
+}
+```
+
+---
+
+## 十、伴生文件清单
+
+后续真正落地组件时需要产出 3 份文件 + 1 处 manifest 更新:
+
+| 文件               | 必需 | 关键内容                                                                                                                                                                                |
+| ------------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `icon.tsx`         | ✅   | 上文第七节实现草稿;每个 prop 必带 JSDoc + `@default`                                                                                                                                    |
+| `icon.meta.md`     | ✅   | 顶部 1~2 行组件描述 + When to use / NOT use + Props marker(`<!-- auto:props:begin -->`)+ Deps marker(`<!-- auto:deps:begin -->`)+ AI 生成纪律段(直接迁本文档第八节)+ 路线图段(第十一节) |
+| `icon.stories.tsx` | ✅   | CSF 3.0,`tags: ['autodocs']`,`meta.parameters.docs.description.component` 写四段式描述,argTypes 覆盖全部 prop;Stories 列表见下表                                                        |
+| `manifest.json`    | ✅   | 追加上文第 9.3 节 entry,**注意 `id` 字典序插入位置**(在 `icon-***` 区,目前没有 icon 前缀的 entry,可放在 `image` 之前)                                                                   |
+
+### 10.1 stories 覆盖清单
+
+| Story                  | 演示重点                                              |
+| ---------------------- | ----------------------------------------------------- |
+| `Playground`           | 全 prop 可控(默认 story,argTypes 暴露全集)            |
+| `Sizes`                | 5 档 size + inherit 横排对比(同图标 Smile)            |
+| `Tones`                | 6 档 tone 横排对比(同 size md)                        |
+| `Spinning`             | `spin=true`,搭配 `Loader2`                            |
+| `Rotated`              | rotate 0 / 45 / 90 / 180 度横排                       |
+| `WithAriaLabel`        | 非装饰场景,`decorative={false}` + `aria-label`        |
+| `AsChild`              | Slot 模式包裹自定义元素                               |
+| `WithChildren`         | children 通道传任意自定义 SVG                         |
+| `WithBackgroundCircle` | `withBackground=true shape="circle"`,5 档 bgTone 横排 |
+| `WithBackgroundSquare` | `withBackground=true shape="square"`,5 档 bgTone 横排 |
+| `BgToneMatrix`         | 5 档 size × 5 档 bgTone 矩阵展示(2 行 shape)          |
+
+### 10.2 stories 中 icon mapping 范例
+
+```typescript
+import { Smile, Check, AlertTriangle, Loader2, Search, Trash2, Settings, Info } from 'lucide-react';
+
+const iconMapping = { Smile, Check, AlertTriangle, Loader2, Search, Trash2, Settings, Info };
+
+// argTypes:
+icon: { control: 'select', options: Object.keys(iconMapping), mapping: iconMapping };
+```
+
+### 10.3 四段式 description 草稿
+
+> **Icon 图标容器 —— 在 UI 中承载图形语义、状态指示、装饰点缀。基于 `lucide-react` 默认源 + 自定义 SVG / iconfont 工厂(v0.2)双通道,提供 5 档尺寸、6 档语义 tone、spin/rotate 动效、Slot 包装、装饰/非装饰无障碍开关。承接 cloud-design Icon 的 `iconBackgroundType/Color` 能力,新增 `withBackground` + `shape` + `bgTone`,把"圆形/方形 + 彩色背景的 icon 容器"沉淀为单一 prop;shadcn 无对标,antd `@ant-design/icons` 提供 `spin / rotate`:关键 prop `icon`、`size`、`tone`、`spin`、`rotate`、`withBackground`、`shape`、`bgTone`、`decorative`、`asChild`。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。**
+
+---
+
+## 十一、后续扩展点路线图
+
+| 阶段        | 能力                                                                        | 落地形式                                                                                                                                                                                                                                      |
+| ----------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| v0.1 (本期) | 默认 lucide 源 + 背景容器 + 5 档 size + 6 档 tone + spin/rotate/Slot/无障碍 | 见上文                                                                                                                                                                                                                                        |
+| v0.2        | iconfont 工厂                                                               | `createIconfontIcon({ scriptUrl: string }): React.FC<{ type: string }>` 返回与 IconProps `children` 通道兼容的组件,使用方式 `<Icon icon={undefined}><MyIconfont type="store" /></Icon>` 或更短的 `<MyIconfont type="store" />` 直接当作子节点 |
+| v0.3+       | 多 icon set 工厂                                                            | heroicons / tabler 等同样以工厂模式注入,组件本身仍保持 lucide 默认源,**API 不变**                                                                                                                                                             |
+| 可选        | string name 注册表                                                          | 若业务侧确有 `<Icon type="smile" />` 习惯保留诉求,提供 opt-in `iconRegistry` 工厂(不强制全量打包)                                                                                                                                             |
+
+> **API 在 v0.1 就稳定** —— 后续加源不破坏现有 prop。这是本组件最大的"为什么要包一层"的依据。
+
+---
+
+## 十二、验证步骤
+
+按 ui 包标准动作执行:
+
+```bash
+# 1. 生成 props 表与依赖表(从 IconProps JSDoc + manifest.json 渲染到 icon.meta.md marker 区)
+pnpm --filter @teamix-evo/ui gen:meta
+
+# 2. 校验 manifest schema + 文件路径 + 依赖图无环
+pnpm --filter @teamix-evo/ui validate
+
+# 3. 类型检查
+pnpm --filter @teamix-evo/ui typecheck
+
+# 4. 启动 storybook,在 autodocs 页验证:
+#    - 顶部组件描述渲染正确(四段式)
+#    - Props 表完整(由 react-docgen-typescript 从 icon.tsx 抽取)
+#    - 11 个 story 都能渲染
+#    - 切换主题变体(toolbar)确认 tone / bgTone 跟随 token 变化
+pnpm --filter @teamix-evo/ui storybook
+
+# 5. 防漂移检查(meta props 表 + 依赖表与源码 / manifest 一致)
+pnpm --filter @teamix-evo/ui gen:check
+
+# 6. 视觉与 a11y 对照 design checklist 8 项
+#    skill: teamix-evo-design-opentrek/checklist.md
+```
+
+---
+
+## 十三、与 cloud-design Icon 的差异总结
+
+| 维度      | cloud-design Icon                                        | teamix-evo Icon                                                   |
+| --------- | -------------------------------------------------------- | ----------------------------------------------------------------- |
+| icon 源   | `@alifd/next` 内置字典 + iconfont 工厂(运行时主题包驱动) | `lucide-react` 默认 + iconfont 工厂(v0.2) + children 通道         |
+| 选择方式  | `type="smile"` 字符串查表                                | `icon={Smile}` 组件直传(tree-shaking 友好)                        |
+| size 档位 | 9 档 + inherit + number                                  | 5 档 + inherit(收敛)                                              |
+| 配色      | `style.color` 自由 + cloud-design 主题包覆盖默认色       | `tone` 6 档语义色(走 tokens)                                      |
+| 背景容器  | 不在 Icon 内部,需要在 ProPageHeader 等容器里手拼         | **集成到 Icon 内**(`withBackground`),单一 prop 即得视觉一致的容器 |
+| 旋转      | 不支持                                                   | `rotate` + `spin`                                                 |
+| 无障碍    | 文档约束                                                 | 运行时默认 `aria-hidden`,非装饰强制 `aria-label`                  |
+| 主题机制  | 主题包 npm,运行时切换                                    | 设计 tokens(CSS vars),编译期 + CSS 切换                           |
+
+---
+
+## 十四、研发任务拆分
+
+| #   | 任务                                                   | 输入              | 输出                                                           |
+| --- | ------------------------------------------------------ | ----------------- | -------------------------------------------------------------- |
+| 1   | 建目录 + 三件套空壳                                    | 本文档            | `src/components/icon/{icon.tsx,icon.meta.md,icon.stories.tsx}` |
+| 2   | 写 cva 与 Props 类型                                   | 本文档第六/四节   | `iconInnerVariants` / `iconContainerVariants` / `IconProps`    |
+| 3   | 写组件实现(三个分支)                                   | 本文档第七节      | `Icon` forwardRef 组件                                         |
+| 4   | 写 stories(11 个 + autodocs description)               | 本文档第十节      | `icon.stories.tsx`                                             |
+| 5   | 写 meta(描述 + 何时用 / 不用 + AI 生成纪律 + 路线图)   | 本文档第八/十一节 | `icon.meta.md`                                                 |
+| 6   | 加 manifest.json entry                                 | 本文档第 9.3 节   | manifest 字典序插入                                            |
+| 7   | 跑 `gen:meta` / `validate` / `typecheck` / `gen:check` | 任务 1~6 产物     | 本地校验通过                                                   |
+| 8   | 跑 storybook,过 design checklist 8 项                  | 任务 7 后         | 视觉与 a11y 验收通过                                           |
+
+---
+
+## 十五、注意事项 & AI 生成纪律(交付前自检)
+
+- [ ] 每个 prop 都有 JSDoc + `@default`(供 `gen:meta` 读取)
+- [ ] `icon.meta.md` 顶部 1~2 行组件描述已写
+- [ ] `icon.meta.md` 含 "AI 生成纪律" 小节(直接迁本文档第八节)
+- [ ] `icon.meta.md` 含 `<!-- auto:deps:begin --> <!-- auto:deps:end -->` marker
+- [ ] `icon.stories.tsx` 的 `meta.parameters.docs.description.component` 已填写四段式描述
+- [ ] manifest.json 已加 entry,registryDependencies 列入 `cn`,dependencies 列入 `@radix-ui/react-slot` / `cva` / `lucide-react`
+- [ ] `pnpm --filter @teamix-evo/ui validate` 通过
+- [ ] `pnpm --filter @teamix-evo/ui gen:check` 通过
+- [ ] 11 个 story 在 storybook 可见,切换主题 tone / bgTone 颜色随之变化
+- [ ] design checklist 8 项(色彩 / 排版 / 圆角 / 间距 / 阴影 / 动效 / 一致性 / 安全)逐项过关
+- [ ] 不绕过 ESLint `teamix-evo/icon-from-lucide` 规则;本组件作为该规则的官方收口出口
+
+---
+
+## 附录 B · v0.1 内部 API 收敛纪录
+
+> 本节记录 Icon 组件在 v0.1 进入 stable 之前一次性发生的 API 收敛。原始设计来自本文档第四/六/七节(`icon` / `tone` / `size` / `withBackground` / `shape` / `bgTone` 6 prop),最终落地为 `children` / `variant` / `tone` / `size` / `spin` / `rotate` / `asChild` / `decorative`。本次收敛**只发生在 v0.1 内部**,后续 stable 版本不再变动。
+
+### 决策摘要
+
+| 维度      | 初版(本文档原稿)                                          | 终版(v0.1 落地)                                        | 决策 reference                                                               |
+| --------- | --------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| 图标入口  | `icon: LucideIcon` prop                                   | `children: ReactNode` 必填(单一通道)                   | Mantine ThemeIcon `<ThemeIcon><IconSun /></ThemeIcon>` 范式                  |
+| 形态      | `withBackground: boolean` + `shape: round/square` 两 prop | `variant: 'plain' \| 'circle' \| 'square'` 三档枚举    | Radix Themes / Mantine ThemeIcon `variant` 单 prop 表达形态                  |
+| 配色      | `tone` + `bgTone` 两 prop(前景/背景独立)                  | `tone` 单轴(带背景时由同一 token 派生浅底深字)         | Polaris `tone` 在 token-based 体系下表意更准;`bgTone` 在视觉上无独立调色需求 |
+| 尺寸      | 5 档(xs/sm/md/lg/xl) + inherit                            | 7 档(xs/sm/md/lg/xl/2xl/3xl) + inherit                 | 对齐 Tailwind v4 / Radix Themes 命名;7 档覆盖 12px → 48px 完整业务尺度       |
+| 默认 size | `md = 16px`(size-4)                                       | `md = 20px`(size-5)                                    | 与设计稿(7 档示意图)对齐,避免默认偏小                                        |
+| 透传      | className 部分透传                                        | `className` / `style` 在三个分支均完整透传到外层根节点 | 修复 `withBackground` 分支 `style` 丢失 bug                                  |
+
+### 决策依据
+
+1. **业界范式对照**(共调研 6 家):shadcn 不做 / MUI 分离 / **Mantine ThemeIcon variant 合一(范式参考)** / Chakra `as` prop / **Radix Themes variant + color(范式参考)** / Ant Design 配置式。Mantine ThemeIcon 的 children 通道 + variant 单 prop 同时被多家采纳,是当前最稳的折衷。
+2. **`tone` vs `color` 取舍**:`color` 是绝对主流(Mantine/MUI/Chakra/Radix Themes/AntD),`tone` 是 Polaris 标杆。本仓库 token-based + uni-manager 多变体,`tone` 比 `color` 更能表达"语义"而非"颜色值"。
+   ⚠️ **二次回退**:本决策后续被 ADR 0021 推翻 — `tone` 实测在业界仅 Polaris 一家,不在 antd / shadcn 消费方认知词典内。二次回退详见**附录 C**。
+3. **size 不进 tokens 包**:Tailwind v4 默认 `--spacing: 0.25rem` spacing scale 已覆盖 12/16/20/24/28/36/48px。Icon size 不是品牌差异轴,无需进 tokens。
+4. **第零条准则**:能力做 shadcn ∪ antd ∪ cloud-design 并集(保留 `spin` / `rotate` / 带背景容器),理念跟 design(token-based 配色,不裸 hex)。
+
+### 影响面
+
+- **PageHeader**:从 `<Icon icon={Cloud} withBackground bgTone="primary" size="lg" />` 改为 `<Icon variant="circle" tone="primary" size="lg"><Cloud /></Icon>`。
+- **ESLint `teamix-evo/icon-from-lucide`**:不变。Icon 仍是 lucide 收口出口,只是入口由 `icon` prop 改为 children。
+- **本文档第四/六/七/十节**:历史描述保留以便追溯决策路径,实现以 `icon.tsx` / `icon.stories.tsx` / `icon.meta.md` 为准。
+
+---
+
+## 附录 C · ADR 0021 二次回退(tone → color)
+
+> v0.1 发布后一轮全仓 grep 发现:Tag/Timeline/Typography Text 等取 antd `color`/`type`,Icon/Spinner 取 Polaris `tone`,双轨同在 — 起草 ADR 0021 治理,初版(上午)采 `tone` + `status` 三分。同日下午用户质疑 `tone` 业界流行度,复插后发现:`tone` 在 6 家代表体系(shadcn / antd / MUI / Mantine / Chakra / Polaris)中仅 Polaris 一家采用,不在业界认知主流。ADR 0021 正式版(下午)从 `tone` 二次回退到 `color`。
+
+### 差异点
+
+| 维度      | 附录 B(v0.1 初调)                                                       | 附录 C(ADR 0021 二次回退)                                                          |
+| --------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| prop 名   | `tone`                                                                  | **`color`**                                                                        |
+| 枚举字面  | default / muted / primary / destructive / success / warning             | default / muted / primary / success / warning / destructive(仅顺序微调)            |
+| 形态 prop | `variant: plain/circle/square` 三档枚举                                 | 不变                                                                               |
+| 论据      | Polaris `tone` 在 token-based 体系表意更准;Spinner 已设下 `tone` 可复用 | 业界主流 5/6 家都用 `color`/`variant`,`tone` 仅 Polaris 孤本;antd 消费方零迁移成本 |
+
+### 影响面
+
+- **icon.tsx**:`iconInnerVariants.tone` → `.color`;`iconContainerVariants.tone` → `.color`;`IconTone` 类型 → `IconColor`;默认 `defaultVariants` 同改。
+- **icon.stories.tsx**:`TONES` const 改名 `COLORS`;argTypes/args 中 `tone` → `color`;所有 `<Icon tone="...">` → `<Icon color="...">`;描述文案同步。
+- **上游消费方**:PageHeader / Tag / Timeline / Typography Text / Spinner 等同步 `tone` → `color`(本 ADR 一次性迁移)。
+- **附录 B 决策依据第 2 条**(`tone` vs `color` 取舍):原文保留为演进档案,同时在原句下加了"二次回退"提示。
+
+### 决策者提醒
+
+- 本文档第一、二、三、四、五、六节(及附录 B)中出现的 `tone` 字样均为演进档案术语,不代表当前实现。
+- 当前实现以 [icon.tsx](./icon.tsx) / [icon.stories.tsx](./icon.stories.tsx) / [icon.meta.md](./icon.meta.md) / [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md) 为准。
+
+---
+
+## 附录 A · 关键参考链接
+
+- 源头组件:[cloud-design Icon](file:///Users/lyca/Documents/workspace/teamix/cloud-design/base-components/src/icon/index.tsx) / [index.md](file:///Users/lyca/Documents/workspace/teamix/cloud-design/base-components/src/icon/index.md)
+- 范本组件:[Spinner](../spinner/spinner.tsx) — lucide 轻封装的最简范本
+- 关联组件:[PageHeader](../page-header/DEVELOPMENT.md) — `withBackground` 能力的首个消费者
+- ui 包入口:[AGENTS.md](../../../AGENTS.md) — 第零条准则与工程约束
+- ESLint 规则:[`@teamix-evo/eslint-config`](../../../../eslint-config/) — `teamix-evo/icon-from-lucide` 等
+- design 哲学:`teamix-evo-design-opentrek/philosophy.md` / `foundations.md` / `boundaries.md` / `checklist.md`
+- 关联 ADR:[ADR 0008](../../../../../docs/adr/0008-eslint-visual-rules-warn-baseline.md) — visual rules warn baseline(success/warning token 缺口处置)