@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/page-header/DEVELOPMENT.md

@@ -0,0 +1,842 @@
+# PageHeader 组件研发文档
+
+> 本文档为 `@teamix-evo/ui` PageHeader 组件的完整研发分析,基于 teamix-pro 中 `ProPageHeader` 的功能 fork,按照 ui 库第零条准则（能力做并集,理念跟 design,工程跟 shadcn）重新设计实现。
+
+---
+
+## 一、源头分析 — ProPageHeader（teamix-pro）
+
+### 1.1 原始组件定位
+
+ProPageHeader 是面向控制台/中后台场景的页头组件,一般用于详情页、表单页或列表页的顶部区域,承载以下信息层次：
+
+| 层次       | 内容                                 | 原始实现位置                      |
+| ---------- | ------------------------------------ | --------------------------------- |
+| 导航层     | 面包屑 + 右上角额外链接              | 第一层 section (nav + extra)      |
+| 标题层     | 返回按钮 + 图标 + 标题 + 标签 + Tabs | 第二层 section left (title)       |
+| 描述层     | 描述文案                             | 第二层 section left (description) |
+| 数据概览层 | 统计卡片组                           | 第二层 section right (data)       |
+| 操作层     | 按钮组                               | 第二层 section right (operation)  |
+| 详情层     | 结构化信息面板                       | 第三层 section (info)             |
+| 背景装饰层 | 右下角背景图                         | header style backgroundImage      |
+
+### 1.2 原始 Props 清单
+
+```typescript
+type ProPageHeaderProps = {
+  title?: React.ReactNode;
+  titleTooltip?: React.ReactNode;
+  description?: React.ReactNode;
+  icon?: React.ReactNode;
+  iconColor?: 'blue' | 'green' | 'orange' | 'red' | 'yellow' | string;
+  iconBackgroundType?: 'circle' | 'square';
+  iconBackgroundColor?: Color;
+  goback?: boolean | LinkPath | ((e: React.MouseEvent) => void);
+  image?: string;
+  loading?: boolean;
+  breadcrumb?: ProPageHeaderBreadcrumbItem[];
+  extra?: ProActionGroupProps | React.ReactNode | any[];
+  operation?: ProActionGroupProps | React.ReactNode | any[];
+  tags?: ProPageHeaderTagItem[];
+  data?: ProPageHeaderDataItem[];
+  info?: ProInfoProps | React.ReactNode;
+  tabs?: CapsuleTabType;
+} & Omit<React.HTMLAttributes<HTMLElement>, 'title'>;
+```
+
+### 1.3 原始依赖关系
+
+| 依赖组件              | 来源                       | 作用       |
+| --------------------- | -------------------------- | ---------- |
+| Breadcrumb            | @ali/alicloudfe-components | 面包屑导航 |
+| TeamixIcon            | @ali/teamix-icon           | 图标渲染   |
+| Tooltip/Balloon       | @ali/alicloudfe-components | 标题提示   |
+| ProActionGroup        | ../actions                 | 按钮操作组 |
+| ProInfo               | ../info                    | 详情面板   |
+| CapsuleTab            | ../field                   | 选项卡切换 |
+| ProSkeletonRaw        | ../skeleton                | 骨架屏加载 |
+| ProTagItem/renderTags | ../field                   | 标签渲染   |
+
+---
+
+## 二、第零条准则对照表（三层对齐）
+
+### 2.1 能力对标 — shadcn ∪ antd 并集
+
+> shadcn 没有 PageHeader 原子组件,antd 在 v5 已废弃 `PageHeader` 并移至 `@ant-design/pro-components`。本组件属于 **antd 有对标(ProComponents)、shadcn 无对标** 的类型,功能全面承接 antd ProPageHeader。
+
+| 能力维度   | antd/Pro 提供                 | shadcn 提供 | 本组件实现                          |
+| ---------- | ----------------------------- | ----------- | ----------------------------------- |
+| 标题       | ✅ title + subTitle           | ❌          | ✅ title（ReactNode 自由渲染）      |
+| 标题提示   | ❌                            | ❌          | ✅ titleTooltip（teamix-pro 特色）  |
+| 返回按钮   | ✅ onBack                     | ❌          | ✅ goBack（多态：布尔/路径/函数）   |
+| 面包屑     | ✅ breadcrumb (routes)        | ❌          | ✅ breadcrumb（复用 ui/breadcrumb） |
+| 标签组     | ✅ tags                       | ❌          | ✅ tags（复用 ui/tag）              |
+| 额外操作   | ✅ extra                      | ❌          | ✅ extra（ReactNode，自由度更高）   |
+| 描述       | ❌（ProComponents 有）        | ❌          | ✅ description                      |
+| 图标       | ❌（ProComponents 有 avatar） | ❌          | ✅ icon + iconVariant               |
+| 数据概览   | ❌（ProComponents 有）        | ❌          | ✅ data（统计卡片组）               |
+| 操作按钮组 | ✅ extra (antd 统一放 extra)  | ❌          | ✅ actions（主操作区）              |
+| 详情面板   | ❌（ProComponents 有）        | ❌          | ✅ footer（ReactNode）              |
+| Tabs 切换  | ✅ tabList + tabActiveKey     | ❌          | ✅ tabs（复用 ui/tabs）             |
+| 背景装饰图 | ❌（teamix-pro 特色）         | ❌          | ✅ backgroundImage                  |
+| 加载骨架屏 | ❌（ProComponents 有）        | ❌          | ✅ loading（复用 ui/skeleton）      |
+| 响应式     | ❌                            | ❌          | ✅ 通过 Tailwind 响应式 utilities   |
+
+### 2.2 设计理念 — 跟 `@teamix-evo/tokens` OpenTrek 体系
+
+- 颜色走 semantic tokens：`text-foreground`、`text-muted-foreground`、`bg-muted`、`border-border` 等
+- 间距走 4px 倍数体系：`gap-2`(8px)、`gap-4`(16px)、`p-6`(24px) 等
+- 字号走 tokens 档位：标题 `text-2xl`(24px)、描述 `text-sm`(14px)、数据标题 `text-xs`(12px)
+- 圆角走五档：图标 `rounded-md`(square) / `rounded-full`(circle)
+- 不使用 ProPageHeader 原有的 CSS 变量体系(`--color-text1-*` / `--s-*` / `--font-size-*`)
+- 不照搬 antd 或 teamix-pro 的蓝/绿/红预设色,改用 semantic color system
+
+### 2.3 代码实现 — 跟 shadcn
+
+- **文件结构**：`src/components/page-header/page-header.tsx` + `.meta.md` + `.stories.tsx`
+- **cva 范式**：图标变体（颜色/形状）用 `cva`
+- **forwardRef**：所有导出组件用 `React.forwardRef`
+- **假路径 import**：`@/utils/cn`、`@/components/xxx`
+- **TypeScript strict**：所有 props 有 JSDoc + `@default`
+- **Tailwind CSS**：所有样式通过 Tailwind utilities + semantic tokens
+- **无运行时主题**：不建 ConfigProvider,不引入 less/scss
+
+---
+
+## 三、组件拆分设计
+
+### 3.1 复合组件结构（Compound Components 模式）
+
+遵循 shadcn 风格（对标 Card / Dialog / Command 的复合拆分思路），纯组合式导出,**不保留 ProPageHeader 的配置式能力**,用户自由组装：
+
+```typescript
+// ─── 导出清单 ────────────────────────────────────────────────────
+export { PageHeader }; // 顶层容器 <header>，负责背景图 + 间距
+export { PageHeaderNav }; // 导航层：面包屑 + 右侧额外链接
+export { PageHeaderHeading }; // 标题区域：返回 + Icon + 标题文字 + tooltip + tags
+export { PageHeaderDescription }; // 描述文字
+export { PageHeaderActions }; // 操作按钮区（右对齐）
+export { PageHeaderContent }; // 中间主区域容器（left + right flex 布局）
+export { PageHeaderData }; // 数据概览容器
+export { PageHeaderDataItem }; // 单个数据项（label + value）
+export { PageHeaderFooter }; // 底部区域（详情/自定义内容）
+export { PageHeaderSkeleton }; // 整体骨架屏（loading 态一键替换）
+```
+
+**设计哲学**：每个子组件只做一件事（布局 or 语义），不接受配置对象。用户用 `<Breadcrumb>` / `<Tag>` / `<Button>` 等原子组件自行填充内容,PageHeader 只提供**排版骨架**。
+
+### 3.2 复用的原子组件映射
+
+| ProPageHeader 原始依赖 | teamix-evo/ui 对应组件       | 复用方式                            |
+| ---------------------- | ---------------------------- | ----------------------------------- |
+| Breadcrumb             | `@/components/breadcrumb`    | 直接 import + 组合                  |
+| TeamixIcon             | `lucide-react`               | 替换为 lucide 图标                  |
+| Tooltip/Balloon        | `@/components/tooltip`       | 直接 import                         |
+| ProActionGroup         | `@/components/button` + Slot | 不封装 ActionGroup,用户传 ReactNode |
+| ProSkeletonRaw         | `@/components/skeleton`      | 直接 import + 组合                  |
+| ProTagItem/renderTags  | `@/components/tag`           | 直接 import                         |
+| CapsuleTab             | `@/components/tabs`          | 用 Tabs 组件(Segmented 变体)        |
+| ProInfo                | `@/components/descriptions`  | 复用 Descriptions 组件              |
+| classnames             | `@/utils/cn`                 | 用 cn() 替代                        |
+
+### 3.3 关键设计决策
+
+| 决策点         | teamix-pro 做法                         | teamix-evo/ui 做法                               | 原因                                          |
+| -------------- | --------------------------------------- | ------------------------------------------------ | --------------------------------------------- |
+| 整体范式       | 单一巨组件 + 配置对象驱动               | 纯复合组件,用户组装                              | shadcn 理念 = composable, 不做 props 配置封装 |
+| 操作区 API     | `ProActionGroupProps` 配置式            | children 直接传 Button                           | 无需二次抽象,用户自由度最大                   |
+| 面包屑 API     | `breadcrumb: BreadcrumbItem[]` 配置数组 | 用户直接用 `<Breadcrumb>` 组合                   | 复用已有原子组件,零额外 API                   |
+| 标签 API       | `tags: TagItem[]` 配置数组              | 用户在 Heading 内放 `<Tag>`                      | 同上                                          |
+| 数据概览       | `data: DataItem[]` 配置数组             | `<PageHeaderData>` + `<PageHeaderDataItem>` 复合 | 保留语义容器但不传配置对象                    |
+| 图标系统       | `TeamixIcon`（字符串 type）             | `lucide-react`（ReactNode 直接传入）             | 工程约束: icon 固定来源 lucide-react          |
+| 颜色预设       | 字面色名 `blue/green/red/yellow`        | 语义色 `primary/success/warning/error/info`      | 对齐 design tokens semantic system            |
+| 路由依赖       | `useRouterHistory` + `goToLink`         | 纯回调 `onBack`,不内置路由                       | 源码注入式无法假设路由库                      |
+| 全局 props HOC | `withGlobalProps`                       | 不需要                                           | 无运行时主题体系                              |
+| 样式方案       | SCSS + CSS 变量                         | Tailwind utilities + cn()                        | 工程跟 shadcn                                 |
+| 骨架屏         | 内置专属骨架子组件                      | `<PageHeaderSkeleton>` 组合 Skeleton 原子        | 复用原子组件,不重复造轮子                     |
+
+---
+
+## 四、Props 接口设计（纯复合组件）
+
+每个子组件只暴露自身需要的 props,**不接收配置对象、不做内部循环渲染**。
+
+### 4.1 PageHeader — 顶层容器
+
+```typescript
+export interface PageHeaderProps extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * 右下角背景装饰图 URL。通过 inline style 注入。
+   */
+  backgroundImage?: string;
+  /** 子内容(复合子组件)。 */
+  children?: React.ReactNode;
+}
+```
+
+### 4.2 PageHeaderNav — 导航层
+
+```typescript
+export interface PageHeaderNavProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** 导航层内容(通常左侧放 Breadcrumb,右侧放额外链接)。 */
+  children?: React.ReactNode;
+}
+```
+
+### 4.3 PageHeaderHeading — 标题区域
+
+```typescript
+export interface PageHeaderHeadingProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 前置返回按钮。为 `true` 时渲染 ArrowLeft icon,点击触发 `onBack`。
+   * @default false
+   */
+  goBack?: boolean;
+  /** 返回按钮点击回调。 */
+  onBack?: (e: React.MouseEvent) => void;
+  /** 标题内容。建议用 `<Icon>` + `<Title level={2}>` + `<Tag>` 等原子组件自由组合。 */
+  children?: React.ReactNode;
+}
+```
+
+> **标题文字规范**：推荐用户在 `<PageHeaderHeading>` 内使用 `<Title level={2}>` 组件(来自 `@/components/typography`)作为标题文字载体,对应 `text-2xl font-semibold tracking-tight` —— 这与原 ProPageHeader 的 24px/500 标题视觉一致,同时复用 Typography 原子组件的语义化 HTML 标签(`<h2>`)。`PageHeaderHeading` 自身不强制字号,只做 flex 布局容器。
+>
+> **图标规范**：图标展示（含背景色/形状/尺寸变体）由后续独立的 `<Icon>` 原子组件统一实现。PageHeader 不内置图标逻辑,用户在 children 中放置 `<Icon>` 组件即可。`<Icon>` 将承载 cva 变体（color / shape / withBackground）。
+
+### 4.4 PageHeaderDescription — 描述文字
+
+```typescript
+export interface PageHeaderDescriptionProps
+  extends React.HTMLAttributes<HTMLParagraphElement> {
+  children?: React.ReactNode;
+}
+```
+
+### 4.5 PageHeaderContent — 主内容区容器
+
+```typescript
+/** 包裹 Heading + Description(左) 与 Actions + Data(右) 的 flex 容器。 */
+export interface PageHeaderContentProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  children?: React.ReactNode;
+}
+```
+
+### 4.6 PageHeaderActions — 操作按钮区
+
+```typescript
+export interface PageHeaderActionsProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** 操作按钮(直接放 <Button> 组件)。 */
+  children?: React.ReactNode;
+}
+```
+
+### 4.7 PageHeaderData — 数据概览容器
+
+```typescript
+export interface PageHeaderDataProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  children?: React.ReactNode;
+}
+```
+
+### 4.8 PageHeaderDataItem — 单个数据项
+
+```typescript
+export interface PageHeaderDataItemProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** 数据标题/标签。 */
+  label: React.ReactNode;
+  /**
+   * 值的语义色。
+   * @default "default"
+   */
+  color?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
+  /** 数据值(children)。 */
+  children?: React.ReactNode;
+}
+```
+
+### 4.9 PageHeaderFooter — 底部区域
+
+```typescript
+export interface PageHeaderFooterProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  children?: React.ReactNode;
+}
+```
+
+### 4.10 PageHeaderSkeleton — 骨架屏
+
+```typescript
+export interface PageHeaderSkeletonProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** 是否显示面包屑骨架行。 @default true */
+  showNav?: boolean;
+  /** 是否显示描述骨架行。 @default true */
+  showDescription?: boolean;
+  /** 是否显示底部详情骨架。 @default false */
+  showFooter?: boolean;
+}
+```
+
+---
+
+## 五、渲染结构设计
+
+每个子组件对应一个 HTML 节点,用户自由组装。以下是推荐的典型组合结构：
+
+```
+<PageHeader>                               <!-- <header> 容器, 背景图 -->
+  ├── <PageHeaderNav>                     <!-- flex justify-between 导航层 -->
+  │   ├── <Breadcrumb>...</Breadcrumb>    <!-- 用户自己组装原子 Breadcrumb -->
+  │   └── <div>...</div>                  <!-- 右侧额外链接 / 操作 -->
+  │
+  ├── <PageHeaderContent>                 <!-- flex justify-between 主内容层 -->
+  │   ├── <div.left>                      <!-- 左侧: heading + description -->
+  │   │   ├── <PageHeaderHeading>         <!-- flex items-center 标题行 -->
+  │   │   │   ├── [ArrowLeft goBack]     <!-- 返回按钮 -->
+  │   │   │   ├── [icon + bg]            <!-- 用户传入的图标 -->
+  │   │   │   ├── {children}             <!-- 标题文字 + Tooltip + Tag 等 -->
+  │   │   │   └── ...
+  │   │   └── <PageHeaderDescription> <!-- <p> 描述 -->
+  │   └── <div.right>                     <!-- 右侧: data + actions -->
+  │       ├── <PageHeaderData>            <!-- flex gap 数据概览 -->
+  │       │   ├── <PageHeaderDataItem>
+  │       │   └── ...
+  │       └── <PageHeaderActions>         <!-- flex gap 操作按钮 -->
+  │           └── <Button>... × N
+  │
+  ├── <PageHeaderFooter>                  <!-- 底部区域 -->
+  │   └── <Descriptions>...</Descriptions>  <!-- 或任意自定义内容 -->
+  │
+  └── {children}                          <!-- 其他自定义内容 -->
+</PageHeader>
+```
+
+> **组合自由度**：用户可以省略任何子组件（不需要面包屑就不放 `<PageHeaderNav>`,不需要数据概览就不放 `<PageHeaderData>`）。各子组件**不做内部条件渲染**,存在即渲染。
+
+---
+
+## 5.1 视觉参考拆解（基于 ProPageHeader 实际截图）
+
+![PageHeader 视觉参考](/Users/lyca/Library/Application Support/Qoder/SharedClientCache/cache/images/65c3fc5e/3lyva8ej-2460f75d.png)
+
+从截图中提取的关键视觉规则：
+
+| 区域           | 视觉特征                                                                                  | 实现要点                                                                                         |
+| -------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| **导航层**     | 面包屑用 `/` 分隔符,链接文字与普通文字色差明显;右侧“帮助文档”是带图标的文字链接（非按钮） | `<PageHeaderNav>` 左右两端 flex justify-between;右侧用 variant="link" Button 或纯 anchor         |
+| **返回箭头**   | 与图标、标题同行垂直居中,尺寸约 20px,无背景,cursor pointer                                | `ArrowLeft` from lucide, `size-5`, 无 padding/bg                                                 |
+| **标题图标**   | 蓝色方形背景(`rounded-md`) + 白色图标,背景尺寸约 36×36px,图标居中                         | `iconBackground` + `iconColor="primary"` → `bg-primary text-primary-foreground rounded-md p-1.5` |
+| **标题文字**   | 24px / font-weight 500~600 / 黑色,与图标、Tag 垂直居中                                    | `<Title level={2}>` 提供 `text-2xl font-semibold tracking-tight`                                 |
+| **标签组**     | 与标题同行,间距约 8px;标签三 = filled green / outline green / outline red                 | 用户在 `<PageHeaderHeading>` children 中直接放 `<Tag>` 组件                                      |
+| **操作按钮区** | 右对齐,outline(普通) + primary(主操作) 并排,带图标                                        | `<PageHeaderActions>` 内放 `<Button>` 组件,gap-2                                                 |
+| **描述文字**   | 单独一行,muted 灰色(#5a5a5a),字号 14px                                                    | `<PageHeaderDescription>` → `text-sm text-muted-foreground`                                      |
+| **背景装饰图** | 右下角半透明装饰图,不影响内容层                                                           | `backgroundImage` prop, `bg-right-bottom bg-no-repeat`                                           |
+| **层级间距**   | 导航层 → 标题层 ≈ 8px(mb-2),标题层 → 描述层 ≈ 8px(mt-2)                                   | 各子组件自带 margin 或父容器用 `space-y-2`                                                       |
+
+### 图标背景色的视觉修正
+
+截图中图标背景是**实心蓝色 + 白色 icon**（而非淡蓝背景 + 蓝色 icon）。这意味着 `iconBackground` 为 true 时的 compoundVariant 应该考虑两种模式：
+
+```typescript
+// 模式 A: 淡色背景 + 深色 icon (subtle)
+compoundVariants: [
+  { color: 'primary', withBackground: true, class: 'bg-primary/10 text-primary' },
+  ...
+]
+
+// 模式 B: 实心背景 + 白色 icon (solid) — 截图中是这种
+compoundVariants: [
+  { color: 'primary', withBackground: true, class: 'bg-primary text-primary-foreground' },
+  { color: 'success', withBackground: true, class: 'bg-success text-white' },
+  { color: 'warning', withBackground: true, class: 'bg-warning text-white' },
+  { color: 'error', withBackground: true, class: 'bg-destructive text-white' },
+  ...
+]
+```
+
+建议默认采用 **模式 B（实心背景）** 对齐截图视觉,同时支持通过 className 覆盖为 subtle 模式。
+
+---
+
+## 5.2 更多变体模式视觉参考
+
+### 变体 A: Tabs 切换模式
+
+![Tabs 变体](/Users/lyca/Library/Application Support/Qoder/SharedClientCache/cache/images/65c3fc5e/s7gfasgm-256b65e9.png)
+
+视觉特征：
+
+- **无图标背景**：返回箭头 + 标题文字后直接跟图标切换按钮
+- **图标 Tabs**：3 个 icon-only 切换按钮,用 `|` 分隔符隔开,形态类似 ToggleGroup + Separator
+- **标题行与 Tabs 同层**：所有元素在同一个 flex 行内垂直居中
+- **底部无分割线**：PageHeader 本体不带 `border-b`，与 teamix-pro ProPageHeader 行为对齐；如需与下方内容划分，由页面侧自行补充分隔
+
+实现要点：
+
+- 用户在 `<PageHeaderHeading>` children 中放置 `<ToggleGroup>` 或 `<Separator>` + icons 组合
+- PageHeader 容器不内置 Tabs 逻辑,纯 composable
+
+### 变体 B: 数据概览模式
+
+![Data 变体](/Users/lyca/Library/Application Support/Qoder/SharedClientCache/cache/images/65c3fc5e/uknosvy3-66b0a640.png)
+
+视觉特征：
+
+- **无导航层 / 无返回 / 无图标**：只有标题 + 描述 + 数据
+- **左右分层布局**：左侧 = 标题(粗体 24px) + 描述(灰色 14px);右侧 = 数据概览卡片组
+- **数据项布局**：每项上下结构 — label(上,灰色小字 12px) + value(下,黑色粗体 16px)
+- **彩色值**：“停止”的数值为红色(`text-destructive`)
+- **数据项水平排列**：5 项等距排开,间距约 24px(gap-6)
+- **数字等宽**：使用 `tabular-nums` 保证对齐
+
+`<PageHeaderDataItem>` 内部结构确认：
+
+```tsx
+<div className="flex flex-col">
+  <span className="text-xs text-muted-foreground">{label}</span>
+  <span className={cn('text-base font-semibold tabular-nums', colorClass)}>
+    {children}
+  </span>
+</div>
+```
+
+### 变体 C: 详情面板模式
+
+![Info 变体](/Users/lyca/Library/Application Support/Qoder/SharedClientCache/cache/images/65c3fc5e/y7md1cwr-c71b1b30.png)
+
+视觉特征：
+
+- **圆形图标**：绿色实心圆形背景 + 白色勾选图标,确认 `iconShape="circle"` 变体
+- **操作按钮顺序**：这里 primary 在左,outline 在右（与之前截图相反）,说明顺序由用户自定
+- **Footer 详情区**：
+  - 3 列网格布局,2 行
+  - Label 灰色(小字) + Value 黑色(正常字号)
+  - 状态值带圆点指示器（`● 运行中`）
+  - 某些字段带蓝色链接样式（“优先级”后的数字）
+  - 备注字段可跨列(占 2 列宽度)
+
+实现要点：
+
+- `<PageHeaderFooter>` 内放 `<Descriptions>` 组件(已有原子组件,支持 column/bordered/layout)
+- 状态点由用户自行组合(`<Badge>` 或纯 `<span>` + 圆点)
+
+### 变体 D: Loading 骨架屏
+
+![Skeleton 变体](/Users/lyca/Library/Application Support/Qoder/SharedClientCache/cache/images/65c3fc5e/ydsum9bw-eccc7ca1.png)
+
+视觉特征：
+
+- **第一层**：短条骨架(宽约 200px,高 12px) — 对应面包屑位置
+- **第二层**：中等长条骨架(宽约 360px,高 24px) — 对应标题位置
+- **第三层**：3 列 × 2 行网格骨架条 — 对应 Footer/Info 详情区
+- 各骨架条宽度不一,模拟自然内容长度差异
+- 层级间距与实际内容一致
+
+`<PageHeaderSkeleton>` 确认结构：
+
+```tsx
+<div className={cn('space-y-3', className)} {...props}>
+  {/* Nav 骨架 */}
+  {showNav && <Skeleton shape="line" className="h-3 w-48" />}
+  {/* Title 骨架 */}
+  <Skeleton shape="line" className="h-6 w-80" />
+  {/* Footer/Info 骨架 */}
+  {showFooter && (
+    <div className="grid grid-cols-3 gap-x-8 gap-y-3 pt-3">
+      <Skeleton shape="line" className="h-3 w-full" />
+      <Skeleton shape="line" className="h-3 w-4/5" />
+      <Skeleton shape="line" className="h-3 w-full" />
+      <Skeleton shape="line" className="h-3 w-4/5" />
+      <Skeleton shape="line" className="h-3 w-3/5" />
+      <Skeleton shape="line" className="h-3 w-full" />
+    </div>
+  )}
+</div>
+```
+
+---
+
+## 六、样式方案映射
+
+### 6.1 原始 SCSS → Tailwind 映射表
+
+| ProPageHeader SCSS                                               | Tailwind 等价                                        |
+| ---------------------------------------------------------------- | ---------------------------------------------------- |
+| `position: relative; overflow: hidden`                           | `relative overflow-hidden`                           |
+| `background-position: right bottom`                              | `bg-right-bottom bg-no-repeat bg-[length:auto_100%]` |
+| `display: flex; justify-content: space-between`                  | `flex items-center justify-between`                  |
+| `min-height: 18px; margin-bottom: 8px`                           | `min-h-[18px] mb-2`                                  |
+| `font-size: 24px; font-weight: 500`                              | `text-2xl font-medium`                               |
+| `color: var(--color-text1-4)`                                    | `text-foreground`                                    |
+| `color: var(--color-text1-2)`                                    | `text-muted-foreground`                              |
+| `color: var(--color-text1-8)`                                    | `text-muted-foreground/70`                           |
+| `font-size: 16px; font-family: DIN`                              | `text-base font-semibold tabular-nums`               |
+| `padding-right: 16px`                                            | `pr-4`                                               |
+| `flex-shrink: 0`                                                 | `shrink-0`                                           |
+| `cursor: pointer`                                                | `cursor-pointer`                                     |
+| `white-space: nowrap; overflow: hidden; text-overflow: ellipsis` | `truncate`                                           |
+
+### 6.2 颜色系统映射
+
+| ProPageHeader 颜色           | OpenTrek Semantic Token                  |
+| ---------------------------- | ---------------------------------------- |
+| `--color-notice-5` (blue)    | `text-primary`                           |
+| `--color-success-5` (green)  | `text-success`                           |
+| `--color-warning-5` (orange) | `text-warning`                           |
+| `--color-error-5` (red)      | `text-destructive`                       |
+| `--color-help-5` (yellow)    | `text-warning`（合并,或待 tokens 补）    |
+| icon 背景色预设              | `bg-primary/10` / `bg-success-subtle` 等 |
+
+### 6.3 图标变体 cva 设计
+
+基于截图视觉：图标背景为**实心色 + 白色 icon**（非淡色背景）,方形圆角约 6px,内距约 6px,整体尺寸约 36×36px:
+
+```typescript
+const iconVariants = cva(
+  'inline-flex items-center justify-center shrink-0 [&>svg]:size-5',
+  {
+    variants: {
+      color: {
+        default: 'text-foreground',
+        primary: 'text-primary',
+        success: 'text-success',
+        warning: 'text-warning',
+        error: 'text-destructive',
+        info: 'text-info',
+      },
+      shape: {
+        square: 'rounded-md',
+        circle: 'rounded-full',
+      },
+      withBackground: {
+        true: 'size-9 p-1.5', // 36px 背景块,内距 6px
+        false: '',
+      },
+    },
+    compoundVariants: [
+      // 实心背景 + 白色 icon（对齐截图视觉）
+      {
+        color: 'primary',
+        withBackground: true,
+        class: 'bg-primary text-primary-foreground',
+      },
+      {
+        color: 'success',
+        withBackground: true,
+        class: 'bg-success text-white',
+      },
+      {
+        color: 'warning',
+        withBackground: true,
+        class: 'bg-warning text-white',
+      },
+      {
+        color: 'error',
+        withBackground: true,
+        class: 'bg-destructive text-destructive-foreground',
+      },
+      { color: 'info', withBackground: true, class: 'bg-info text-white' },
+      {
+        color: 'default',
+        withBackground: true,
+        class: 'bg-muted text-muted-foreground',
+      },
+    ],
+    defaultVariants: {
+      color: 'default',
+      shape: 'square',
+      withBackground: false,
+    },
+  },
+);
+```
+
+---
+
+## 七、Loading 骨架屏设计
+
+复用 `@/components/skeleton` 组合实现,不另建专用骨架子组件：
+
+```tsx
+// loading 态布局
+<header className="...">
+  {/* 面包屑骨架 */}
+  <div className="flex items-center gap-2 mb-2">
+    <Skeleton shape="line" className="h-3 w-16" />
+    <Skeleton shape="line" className="h-3 w-16" />
+    <Skeleton shape="line" className="h-3 w-24" />
+  </div>
+  {/* 标题骨架 */}
+  <div className="flex items-center gap-3">
+    <Skeleton shape="rect" className="size-8 rounded-md" />
+    <Skeleton shape="line" className="h-6 w-48" />
+  </div>
+  {/* 描述骨架 */}
+  <Skeleton shape="line" className="mt-2 h-4 w-96" />
+  {/* 详情骨架 */}
+  <SkeletonParagraph rows={2} className="mt-4" />
+</header>
+```
+
+---
+
+## 八、registryDependencies 分析
+
+基于复用的原子组件,manifest.json entry 需声明:
+
+```json
+{
+  "id": "page-header",
+  "name": "PageHeader",
+  "type": "component",
+  "registryDependencies": ["cn", "skeleton"],
+  "dependencies": {
+    "class-variance-authority": "^0.7.0",
+    "lucide-react": "^0.460.0"
+  }
+}
+```
+
+> **为什么只声明 `cn` 和 `skeleton`?** 复合组件模式下,`breadcrumb` / `tag` / `tooltip` / `descriptions` 等原子组件由用户在使用侧自行引入组合,不是 PageHeader 内部的硬依赖。只有 `PageHeaderSkeleton` 内部复用了 `Skeleton` 组件才需要声明。用户 `add page-header` 后,CLI 会提示推荐搭配的原子组件。
+
+---
+
+## 九、使用示例预览
+
+### 9.1 极简用法
+
+```tsx
+import {
+  PageHeader,
+  PageHeaderContent,
+  PageHeaderHeading,
+} from '@/components/page-header';
+import { Title } from '@/components/typography';
+
+<PageHeader>
+  <PageHeaderContent>
+    <PageHeaderHeading>
+      <Title level={2}>实例管理</Title>
+    </PageHeaderHeading>
+  </PageHeaderContent>
+</PageHeader>;
+```
+
+### 9.2 标准用法（面包屑 + 标题 + 标签 + 操作）
+
+```tsx
+import {
+  PageHeader,
+  PageHeaderNav,
+  PageHeaderContent,
+  PageHeaderHeading,
+  PageHeaderActions,
+} from '@/components/page-header';
+import { Title } from '@/components/typography';
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbSeparator,
+  BreadcrumbPage,
+} from '@/components/breadcrumb';
+import { Tag } from '@/components/tag';
+import { Button } from '@/components/button';
+import { Server } from 'lucide-react';
+
+<PageHeader>
+  <PageHeaderNav>
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/">首页</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/resources">资源管理</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>实例详情</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  </PageHeaderNav>
+
+  <PageHeaderContent>
+    <PageHeaderHeading
+      goBack
+      onBack={() => router.back()}
+      icon={<Server className="size-5" />}
+      iconColor="primary"
+      iconBackground
+    >
+      <Title level={2}>i-2ze3m5j8w</Title>
+      <Tag color="success">运行中</Tag>
+      <Tag>华东1</Tag>
+    </PageHeaderHeading>
+
+    <PageHeaderActions>
+      <Button variant="outline">停止</Button>
+      <Button>远程连接</Button>
+    </PageHeaderActions>
+  </PageHeaderContent>
+</PageHeader>;
+```
+
+### 9.3 带数据概览
+
+```tsx
+import {
+  PageHeader,
+  PageHeaderContent,
+  PageHeaderHeading,
+  PageHeaderDescription,
+  PageHeaderData,
+  PageHeaderDataItem,
+} from '@/components/page-header';
+import { Title } from '@/components/typography';
+
+<PageHeader>
+  <PageHeaderContent>
+    <PageHeaderHeading>
+      <Title level={2}>集群总览</Title>
+    </PageHeaderHeading>
+    <PageHeaderDescription>杭州地域集群资源使用情况</PageHeaderDescription>
+    <PageHeaderData>
+      <PageHeaderDataItem label="总实例">456</PageHeaderDataItem>
+      <PageHeaderDataItem label="运行中" color="success">
+        324
+      </PageHeaderDataItem>
+      <PageHeaderDataItem label="已停止" color="error">
+        14
+      </PageHeaderDataItem>
+    </PageHeaderData>
+  </PageHeaderContent>
+</PageHeader>;
+```
+
+### 9.4 带详情面板
+
+```tsx
+import {
+  PageHeader,
+  PageHeaderNav,
+  PageHeaderContent,
+  PageHeaderHeading,
+  PageHeaderFooter,
+} from '@/components/page-header';
+import { Descriptions } from '@/components/descriptions';
+import { Tag } from '@/components/tag';
+
+<PageHeader>
+  <PageHeaderNav>
+    <Breadcrumb>...</Breadcrumb>
+  </PageHeaderNav>
+
+  <PageHeaderContent>
+    <PageHeaderHeading goBack onBack={() => navigate(-1)}>
+      实例详情
+    </PageHeaderHeading>
+  </PageHeaderContent>
+
+  <PageHeaderFooter>
+    <Descriptions
+      column={3}
+      items={[
+        { label: '实例 ID', value: 'i-2ze3m5j8w' },
+        { label: '状态', value: <Tag color="success">运行中</Tag> },
+        { label: '地域', value: '华东1(杭州)' },
+        { label: '创建时间', value: '2026-03-15 10:30:00' },
+      ]}
+    />
+  </PageHeaderFooter>
+</PageHeader>;
+```
+
+### 9.5 背景装饰图
+
+```tsx
+import { Title } from '@/components/typography';
+
+<PageHeader backgroundImage="https://img.alicdn.com/imgextra/...">
+  <PageHeaderContent>
+    <PageHeaderHeading icon={<Cloud />} iconColor="primary" iconBackground>
+      <Title level={2}>云服务器 ECS</Title>
+    </PageHeaderHeading>
+    <PageHeaderDescription>弹性计算服务</PageHeaderDescription>
+  </PageHeaderContent>
+</PageHeader>;
+```
+
+### 9.6 Loading 态
+
+```tsx
+import { PageHeaderSkeleton } from '@/components/page-header';
+
+{
+  loading ? (
+    <PageHeaderSkeleton showNav showDescription />
+  ) : (
+    <PageHeader>...</PageHeader>
+  );
+}
+```
+
+---
+
+## 十、与 ProPageHeader 的差异总结
+
+| 对比项     | ProPageHeader (teamix-pro)  | PageHeader (teamix-evo/ui)            |
+| ---------- | --------------------------- | ------------------------------------- |
+| 组件范式   | 单一巨组件 + 配置驱动       | 纯复合组件,用户自由组装               |
+| 样式方案   | SCSS + CSS 变量             | Tailwind + cn() + semantic tokens     |
+| 图标系统   | TeamixIcon (字符串 type)    | lucide-react (ReactNode 传入)         |
+| 操作区     | ProActionGroupProps 配置式  | children 直接放 Button                |
+| 面包屑     | breadcrumb[] 配置数组       | 用户组合 Breadcrumb 原子组件          |
+| 标签       | tags[] 配置数组             | 用户在 Heading 内放 Tag 原子组件      |
+| 详情面板   | ProInfoProps 配置式         | Footer 内放 Descriptions 或自定义内容 |
+| 路由耦合   | useRouterHistory + goToLink | 纯回调 onBack,不耦合路由              |
+| 颜色预设   | 字面色名 (blue/green/...)   | 语义色名 (primary/success/...)        |
+| 全局配置   | withGlobalProps HOC         | 无,源码注入不需要                     |
+| 选项卡     | CapsuleTab 内置             | 用户自行组合 Tabs 或放 children       |
+| 分发方式   | npm 包引入                  | 源码注入 (teamix-evo ui add)          |
+| TypeScript | 基础类型                    | strict mode + 完整 JSDoc + @default   |
+
+---
+
+## 十一、研发任务拆分
+
+| 序号 | 任务                                | 产出文件                     |
+| ---- | ----------------------------------- | ---------------------------- |
+| 1    | 编写 page-header.tsx 主组件源码     | `page-header.tsx`            |
+| 2    | 编写 page-header.meta.md            | `page-header.meta.md`        |
+| 3    | 编写 page-header.stories.tsx        | `page-header.stories.tsx`    |
+| 4    | 注册 manifest.json entry            | `manifest.json` (追加 entry) |
+| 5    | 运行验证 (`validate` + `typecheck`) | -                            |
+| 6    | Storybook 视觉验证                  | -                            |
+| 7    | gen:meta 同步 props 表              | -                            |
+| 8    | gen:check 确认无漂移                | -                            |
+
+---
+
+## 十二、注意事项 & AI 生成纪律
+
+- **不要**封装任何配置式 API（不接受 `breadcrumb[]` / `tags[]` / `data[]` 等数组 props）,一切由用户组合原子组件实现
+- **不要**在组件内 hardcode 任何 icon 字符串,所有图标由用户通过 `icon` prop 传入（lucide-react 组件）
+- **不要**引入路由库依赖,返回逻辑通过 `onBack` 回调由消费方实现
+- **不要**使用 CSS 变量直接写值,一律走 Tailwind semantic token classes
+- **不要**在子组件内做条件渲染“某个 prop 不存在就不渲染”,存在即渲染的操控权在用户侧
+- **goBack** 图标固定用 `ArrowLeft` from lucide-react
+- **titleTooltip** 用户自行用 `@/components/tooltip` 的 `<Tooltip>` 包裹标题文字
+- **PageHeaderDataItem** 内部用 `tabular-nums` class 保持数字等宽对齐
+- 背景图通过 inline style 的 `backgroundImage` 注入（Tailwind 不支持动态 URL）
+- 每个子组件都用 `React.forwardRef` + `cn()` 透传 className