@teamix-evo/skills 0.5.0 → 0.6.0

package/src/teamix-evo-design-opentrek/patterns/list-page.md

@@ -1,367 +1,295 @@
-# List Page — 列表页模式
-
-> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **ListPage**，并由 Step 3 引导到这里。
-
-> **触发**：用户描述含"列表/表格/查询/检索/卡片管理"。
-> **核心特征**：多条结构化数据 + 搜索/筛选 + 分页。
-> **页面级别**：L1（标题模式 PageHeader，自动继承 Sidebar）。
-
 ---
-
-## 1. 子类型路由
-
-| 子类型              | 关键词                           | 布局                          | 核心组件                            |
-| ------------------- | -------------------------------- | ----------------------------- | ----------------------------------- |
-| **standard**        | "列表"/"表格"/"查询"             | TWO_COL                       | DataTable + Pagination              |
-| **l2-sidebar**      | "分类"/"分组"/"左侧树"           | TWO_COL + 内部 Sidebar(240px) | Sidebar + DataTable                 |
-| **expandable**      | "展开"/"子项"/"详情行"           | TWO_COL                       | DataTable（行内展开）               |
-| **drawer**          | "弹窗列表"/"选择器"              | Drawer 内                     | DataTable ⊂ Drawer                  |
-| **pure-card**       | "纯卡片"/"卡片管理"/"智能体列表" | SINGLE_COL                    | CardGrid + ItemCard + CardActionBar |
-| **standard-card**   | "卡片列表"/"分类卡片"/"资源卡片" | TWO_COL                       | Sidebar + CardGrid + ItemCard       |
-| **view-toggle**     | "视图切换"/"列表卡片切换"        | TWO_COL + ViewToggle          | ViewToggle + DataTable/CardGrid     |
-| **advanced-filter** | "高级筛选"/"更多条件"            | TWO_COL                       | AdvancedFilterPanel + DataTable     |
-
-### 路由优先级
-
-1. "纯卡片"/"卡片管理" → pure-card
-2. "卡片列表"/"分类卡片"/"资源卡片" → standard-card
-3. "视图切换"/"列表卡片" → view-toggle
-4. "高级筛选" → advanced-filter
-5. "展开"/"子项" → expandable
-6. "分类"/"分组"/"左侧树" → l2-sidebar
-7. "弹窗列表"/"选择器" → drawer
-8. 默认 → standard
-
+name: page-rule-list
+parent: page-rule-system
+description: >
+  列表页(PageType: ListPage)路由规则。根据子类型识别关键词，路由到 patterns/ 目录下对应详细规则。
+  共享规则在 _shared/ 目录（表格列元规则 / 操作列规范 / 状态-操作模式）。
+  产品配置在 products/{产品}/ 目录（列定义 / 状态机 / 业务映射）。
+  三层参数化架构（v7.0）：元规则（固化）+ 产品配置（灵活）+ 模式细节。
+  触发：需要列表页规则、匹配列表页模板、生成列表页。
+  Version: 7.8.4
 ---
 
-## 2. Template 组件拼装
+# 列表页路由规则
 
-> 源自 `packages/create/variants/opentrek/src/templates/list-page.tsx`
+> ⚠️ **本文件是高阶路由索引，不含布局实现细节。**
+> **生成页面时必须读取**：
+> - `../pages/list-page/SKILL.md` — 子技能入口（子类型列表 + 属性模型）
+> - `../pages/list-page/patterns/{subtype}.md` — 完整骨架 + DOM 结构 + CSS 约束
+> - `../pages/list-page/_shared/search-combo-spec.md` — SearchCombo 20px 间距硬约束
+> - `../pages/list-page/_shared/action-column-spec.md` — 操作列规范
+>
+> 本文件仅用于：(1) 了解 6 种子类型概览 (2) 快速判断属于哪个子类型
 
-```tsx
-<PageShell background="muted" sidebar={<OpSidebar />}>
-  <OpPageContainer header={<PageHeader title="..." actions={...} />}>
-    {/* children: 以下组件由消费方自由组合 */}
-    <ActionToolbar ... />
-    <DataTable ... />   {/* 或 CardGrid */}
-    <Pagination ... />
-  </OpPageContainer>
-</PageShell>
-```
-
-| Slot         | 注入内容                                          | 来源                               |
-| ------------ | ------------------------------------------------- | ---------------------------------- |
-| `sidebar`    | OpSidebar（左导）                                 | `@/components/business/op-sidebar` |
-| `pageHeader` | PageHeader 整块（title + Tabs + Toolbar 组合）    | `@/components/ui/page-header`      |
-| `children`   | ActionToolbar + DataTable / CardGrid + Pagination | 消费方自组合                       |
-
-**壳层特征**：
+## 1. 类型定义
 
-- PageShell `background="muted"` → 灰底主区
-- OpPageContainer → 内嵌**无边框大白卡**（`bg-card rounded-2xl p-6`）
-- 业务组件直接作为 children，**不要再包 `<Card>`**（白卡单例）
+**页面类型**: ListPage
+**核心特征**: 多条结构化数据的展示、筛选和操作入口
+**识别条件**: 页面包含数据表格（DataTable）或卡片网格（CardGrid）+ 搜索/筛选 + 分页
 
 ---
 
-## 3. 标准结构（设计线框）
-
-```
-┌────────────────────────────────────────────┐
-│ PageHeader: 标题模式              [新建]   │  ← Header zone
-├────────────────────────────────────────────┤
-│ ActionToolbar: 🔍 搜索 [筛选▼] [刷新]      │  ← Toolbar zone
-├────────────────────────────────────────────┤
-│ ▢ ID         │ 状态  │ 创建时间  │ 操作  │  ← Main zone
-│ ▢ ORD-001234 │ 进行中│ 2026-05-13│ ⋯    │
-│ ▢ ORD-001235 │ 已完成│ 2026-05-12│ ⋯    │
-├────────────────────────────────────────────┤
-│ [已选 2 项] 批量审批 / 批量导出 / 批量删除  │  ← BulkActionBar (按需)
-├────────────────────────────────────────────┤
-│        ←  1 / 24 →  [50/页 ▼]   共 1200条 │  ← Footer zone
-└────────────────────────────────────────────┘
-```
+## 2. 子类型路由表
 
----
+| 子类型ID | 识别关键词 | 路由到 | 布局模式 | 核心组件 |
+|----------|-----------|--------|----------|----------|
+| standard | "列表"/"表格"/"查询" | → `patterns/standard-list.md` | 模式D | DataTable + Pagination |
+| l2-sidebar | "分类"/"分组"/"左侧树" | → `patterns/l2-sidebar-list.md` | 模式D + Sidebar | Sidebar(240px) + DataTable |
+| expandable | "展开"/"子项"/"详情" | → `patterns/expandable-list.md` | 模式D | DataTable(行内展开) |
+| drawer | "弹窗列表"/"选择器" | → `patterns/drawer-list.md` | 模式D (Sheet 内) | DataTable ⊂ Sheet |
+| **pure-card** | "纯卡片"/"卡片管理"/"智能体列表" | → `patterns/card-list.md` | 模式A-CARD | CardGrid + ItemCard + CardActionBar |
+| **standard-card** | "卡片列表"/"分类卡片"/"资源卡片" | → `patterns/card-list.md` | 模式D-CARD (TWO_COL) | Sidebar + CardGrid + ItemCard + CardActionBar |
+| **view-toggle** | "视图切换"/"列表卡片切换" | → `patterns/card-list.md` | 模式D + ViewToggle | ViewToggle + CardGrid/DataTable + ItemCard(tile) |
+| advanced-filter | "高级筛选"/"更多条件" | → `patterns/advanced-filter-list.md` | 模式D+ | AdvancedFilterPanel + DataTable |
 
-## 4. 必需组件
+> **v7.2 合并**：原 `pure-card-list.md` / `standard-card-list.md` / `view-toggle-list.md` 三个 patterns 合并为单一 `patterns/card-list.md`，子类型差异在其 §1 差异矩阵中区分。
 
-| 组件                          | 位置    | 说明                                                     |
-| ----------------------------- | ------- | -------------------------------------------------------- |
-| **PageHeader**                | top     | 标题模式(L1 页面);右侧主操作(如「新建」)                 |
-| **ActionToolbar**             | toolbar | 单行 flex(nowrap);左 actions + 中 SearchCombo + 右 tools |
-| **DataTable** 或 **CardGrid** | main    | 二选一,按子类型                                          |
-| **Pagination**                | footer  | 默认 10 条/页(标准列表) / 12 条/页(卡片)                 |
+### 路由判定优先级
 
-**框架级**(自动继承,不在 skill 内声明):Sidebar。
+1. 含"纯卡片"/"卡片管理"关键词 → pure-card
+2. 含"卡片列表"/"分类卡片"/"资源卡片"关键词 → standard-card
+3. 含"视图切换"/"列表卡片"关键词 → view-toggle
+4. 含"高级筛选"关键词 → advanced-filter
+5. 含"展开"/"子项"关键词 → expandable
+6. 含"分类"/"分组"/"左侧树"关键词 → l2-sidebar
+7. 含"弹窗列表"/"选择器"关键词 → drawer
+8. 其他列表场景 → standard（默认）
 
 ---
 
-## 5. SearchCombo 规范
-
-> ListPage 顶部搜索 + 筛选的标准复合组件。**禁止**用 Input + Select 散件拼装。
-
-### 4.1 在 ActionToolbar 中的位置（硬约束）
-
-- SearchCombo 是 ActionToolbar 的**直接子元素**，位于 `.left-actions` 之后、`.right-tools` 之前
-- 与 `.left-actions` 间距 = **20px**
-
-### 4.2 结构
-
-```
-[ 维度Select | 分隔线 | 搜索Input | 搜索Button(图标) ]
-```
-
-- 容器统一 border + radius 6px + height 32px + min-width 200px
-- 内部元素无独立边框
+## 3. 通用属性模型
 
-### 4.3 交互规则
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| layout.type | TWO_COL / SINGLE_COL | 见 `rules/page-frame.json` layoutSelectionRules |
+| layout.frame | L1 | 列表页为 L1 级页面，自动继承 Sidebar（含Logo+产品名）。无面包屑。 |
+| responsive | Desktop ≥1200px(完整), Tablet 768-1199px(横滚), Mobile <768px(不推荐) |
+| pagination.default | 标准列表 10 条/页, 纯卡片 12 条/页 |
 
-| 触发                      | 行为                             |
-| ------------------------- | -------------------------------- |
-| 切换维度                  | input.value 清空 → input.focus() |
-| 输入框回车 / 点击搜索按钮 | 执行搜索 → 重置到第 1 页         |
-| 输入框 hover 显示 ×       | 清空输入 → 维度切回"全部"        |
-| 输入框为空时点搜索        | 清除当前条件 → 重置分页          |
+> **框架组件自动继承**：Sidebar 的存在性由 `rules/page-frame.json` 统一管理，子技能只定义内容区组件。L1 级页面自动包含：Sidebar（顶部Logo+产品名），无面包屑。
 
-### 4.4 FilterTag 展示
+---
 
-- 已应用的搜索条件以 FilterTag 形式展示
-- 单条 Tag 含 `label: value ×`
-- 多条提供「清空全部」链接
+## 4. 组件推荐
 
-### 4.5 搜索维度配置示例
+### 必需组件
 
-> 维度按业务上下文动态配置;默认含「全部」。
+| 组件 | 引用 | 层级 | 位置 | 说明 |
+|------|------|------|------|------|
+| PageHeader | — | ORGANISM | top | 页面标题(18px/medium)，默认无描述 |
+| ActionToolbar | — | ORGANISM | top | 操作工具栏，单行 flex(flex-wrap:nowrap)，左侧创建按钮 + 右侧搜索工具 |
+| Pagination | — | MOLECULAR | bottom | 分页控件 |
 
-```json
-// 默认维度
-[
-  { "label": "全部", "value": "all" },
-  { "label": "名称", "value": "name" },
-  { "label": "ID", "value": "id" }
-]
+> **框架级组件**（自动继承，无需在此声明）：Sidebar 由 `rules/page-frame.json` 统一管理，L1 级页面自动包含。
+> 注：DataTable 为 standard/l2/expandable/drawer/view-toggle 的必需组件；CardGrid 为 standard-card/pure-card/view-toggle 的必需组件。
 
-// ECS 实例列表示例
-[
-  { "label": "全部", "value": "all" },
-  { "label": "实例 ID/名称", "value": "instance" },
-  { "label": "IP", "value": "ip" },
-  { "label": "标签", "value": "tag" }
-]
-```
+### 禁止组件
 
+| 组件 | 约束 | 原因 |
+|------|------|------|
+| Form(ORGANISM) | 禁止直接出现在内容区 | 表单应通过 Dialog/Sheet/FormPage 触发 |
+| Chart(ORGANISM) | 禁止出现在标准列表页 | 图表属于 Dashboard |
+| PageContainer | 禁止嵌套 | 见 `rules/layout-rules.json` |
+| 内联编辑 | 禁止 | 编辑应通过 Sheet/Dialog/FormPage |
+| 拖拽排序 | 禁止 | 表格数据为服务端排序 |
+| 无限滚动 | 禁止 | B2B 管理场景需精确分页 |
+| 悬浮操作栏 | 禁止 | 遮挡数据，可发现性差 |
+| 右键菜单 | 禁止 | 可发现性差，移动端不兼容 |
+| hr/section-divider | 禁止 | 组件间距通过 padding/margin 控制，禁止用分割线分隔 PageHeader/ActionToolbar/DataTable
 ---
 
-## 6. DataTable 规则（核心）
-
-### 5.1 列元规则（每列必备）
-
-| 规则     | 说明                                  |
-| -------- | ------------------------------------- |
-| 唯一 ID  | 用于列宽 / 显隐持久化                 |
-| 显隐规则 | "始终显示" 或 "条件显示" + 触发条件   |
-| 宽度定义 | 固定 px / 百分比 / minmax             |
-| 对齐方式 | left（默认）/ center / right          |
-| 排序能力 | 是否支持服务端排序                    |
-| 固定方向 | left（前缀列）/ right（操作列）/ none |
-| 字体     | ID/IP/Hash 等机器列用 `font-mono`     |
-
-### 5.2 列固定
+## 5.1 Card 内左右对齐【稳定规则 / 硬约束】
 
-- 左固定：Checkbox(48px) + ID/名称（20%）
-- 右固定：操作列（140px）
-- 固定列与滚动列交界处 `box-shadow: 1px 0 0 var(--border)`
-- 固定列 `z-index: 10`，滚动列 `z-index: 1`
+> **这是列表页生成中最容易不稳定的点，必须严格遵守：**
 
-### 5.3 行高
+水平 padding 采用**分层模型 v7.5**，职责严格划分：
 
-- 单行内容：56px
-- 多行内容（如规格列）：72px+
+- **Card.paddingX (20px)** → 提供 Card 外侧边缘 ↔ **非 Table 子组件** (PageHeader / ActionToolbar / BulkActionBar / Pagination) 外缘的外侧呼吸
+- **Table td.paddingX (12px)** → 仅提供中间列与列之间的内部呼吸（相邻 td 12+12=24）
+- **Table 首末列 padding-left/right = 20px** → 表格作为密集数据区，额外享有 20px 视觉缩进
 
-### 5.4 选择框三态
+> 注意：Table 首列内容 X = Card 外缘 + 40px，与 PageHeader / ActionToolbar / Pagination 起始线**不对齐**（这是设计预期）。
 
-| 状态   | 视觉             | 触发            |
-| ------ | ---------------- | --------------- |
-| 未选 ☐ | 默认             | —               |
-| 半选 ☐̲ | 当前页有部分选中 | 自动计算        |
-| 全选 ☑ | 当前页全选       | 点表头 checkbox |
+Card 白卡容器：`padding: 0 var(--card-padding-x)` （上下 0 / 左右 20px）。注意：`--card-padding-x` (20px) 独立于 `--page-container-padding` (16px)，后者为 PageContainer 外层间距。
 
-### 5.5 行选择交互
+| 组件 | 水平 padding | 起始线 X 坐标 | 说明 |
+|------|---------------|-----------------|------|
+| Card 白卡容器 | **20px** | Card 外缘 | `padding: 0 var(--card-padding-x)`【外侧呼吸提供者】 |
+| PageHeader | **0** | Card 外缘 + 20 | 外侧呼吸由 Card.paddingX 提供 |
+| ActionToolbar | **0** | Card 外缘 + 20 | 外侧呼吸由 Card.paddingX 提供 |
+| **Table th / td 中间列** | **12px** | — | 仅提供列间内部呼吸（列间距 24px） |
+| **Table th / td 首列** | `padding-left: 20px` | **Card 外缘 + 40** | 表格额外享有 20px 缩进 |
+| **Table th / td 末列** | `padding-right: 20px` | 末缘 = Card 右缘 - 40 | 同上 |
+| BulkActionBar | **0** | Card 外缘 + 20 | 外侧呼吸由 Card.paddingX 提供 |
+| Pagination | **0** | Card 外缘 + 20 | 外侧呼吸由 Card.paddingX 提供 |
 
-- Checkbox：切换当前行
-- 行点击（非操作区）：跳转 DetailPage
-- Shift+点击：范围选中
-- Ctrl/Cmd+点击：切换单行
-- 选中样式：背景 `bg-accent`（与 Checkbox 选中态一致）
+### 参考 CSS
 
-### 5.6 列宽拖拽
+```css
+.data-table thead th,
+.data-table tbody td { padding: 12px 12px; }
+.data-table thead th:first-child,
+.data-table tbody td:first-child { padding-left: 20px; }
+.data-table thead th:last-child,
+.data-table tbody td:last-child { padding-right: 20px; }
+```
 
-- 拖拽手柄置于列头右边界,宽 2px,`cursor: col-resize`
-- 仅对 `visibility: always` 的列允许拖拽
-- 最小宽度取列定义的 `minWidth`(无定义时默认 100px,状态/监控类窄列 80px)
-- 最大宽度不超过表格宽度的 50%
-- 拖拽过程对 `document.body` 加 `cursor: col-resize` + `user-select: none`,防鼠标越界丢失光标
-- 拖拽结束写入 `localStorage`(key 命名 `columnWidths:{产品ID}`);初始化时读取恢复
-- 列配置弹窗提供「恢复默认列宽」按钮,清 localStorage 后刷新
+### 禁止项
 
-### 5.7 列排序
+- ❌ 禁止在非 Table 子组件 (PageHeader / ActionToolbar / BulkActionBar / Pagination) 重复设置 paddingX（会与 Card.paddingX 叠加为 40px）
+- ❌ 禁止 Table 中间列 td paddingX 不为 12px（列间距不为 24px，与设计不一致）
+- ❌ 禁止 Table 首列 padding-left 为非 20 值（0 / 12 / 16 / 24 都不适用）
+- ❌ 禁止 Table 末列 padding-right 为非 20 值（同上）
+- ❌ 禁止使用 `px-4` / `px-6` 等字面量。Tailwind 唯一可接受模式：`px-3 first:pl-5 last:pr-5`（20px = pl-5 / pr-5）
+- ❌ 禁止在 Card 与子组件之间插入额外的 paddingX 包裹层（如为 `.card-scrollable` 加 paddingX）
 
-- 表头右侧 `⇅` 图标(`text-tertiary`、12px)
-- 升序 `↑` / 降序 `↓` 用 `primary` 色
-- 点击循环:默认 → 升序 → 降序 → 默认
-- 排序状态持久化到 `localStorage`
+### 验证方法
 
-### 5.8 文字换行
+生成后逐项验证：
 
-| 列类型  | 处理                                               |
-| ------- | -------------------------------------------------- |
-| ID / IP | `font-mono` + `word-break: break-all` + `truncate` |
-| 规格    | 多行展示,不截断                                    |
-| 标签    | 最多 3 个 + `+N`,不自动换行                        |
+1. PageHeader 标题左边缘 X = ActionToolbar 首个控件 X = Pagination 左侧起始 X = **Card 左边缘 + 20px**
+2. Table 首列 (checkbox) 内容左边缘 X = **Card 左边缘 + 40px**（20 + 20）
+3. Table 末列内容右边缘 X = **Card 右边缘 - 40px**
+4. Table 相邻两个中间列内容间距 = **24px**（例如「ID」列右边缘 ↔ 「状态」列左边缘）
 
----
+任一不一致即为违反。
 
-## 7. 操作列规范（硬约束）
+### 视觉预期
 
-### 6.1 结构
+- thead 背景、tbody tr `border-bottom`、BulkActionBar 背景、Pagination `border-top` **不延伸到 Card 左右边缘**（Card 左右各保留 20px 白边）
+- 表格首末列内容在此基础上进一步缩进 20px，总体与 Card 边缘保持 40px 距离
+- 这是设计预期行为；表格作为密集数据区，额外的首末列缩进为文本提供更舒适的阅读呼吸
 
-操作列 = 主操作 + 分隔线 + 次要操作 + 分隔线 + 状态操作 + 分隔线 + 更多
+> Token 定义：`rules/design-tokens.json` · `componentSpacing.Card.padding` + `componentSpacing.DataTable.firstLastCellRule` + `componentSpacing.DataTable.horizontalAlignmentRule`
+> 组件详细规范：`rules/component-specs.json` · `C17-Table.horizontalPaddingRule`
 
-| 元素                | 样式     | 禁用                             |
-| ------------------- | -------- | -------------------------------- |
-| 主操作（管理/查看） | 链接样式 | —                                |
-| `\|` 分隔线         | —        | —                                |
-| 次要操作            | 文字按钮 | `opacity-45 pointer-events-none` |
-| 状态操作            | 下拉按钮 | 同上                             |
-| "..." 更多          | Dropdown | —                                |
+---
 
-### 6.2 水平对齐（硬约束）
+## 5.2 ContentCard 表面规则 v7.6【硬约束】
 
-- `text-align: left`，**表头与表体均需显式声明**
-- 表头「操作」左边缘 X = 表体「详情」链接左边缘 X
-- ❌ 禁止操作列内容居中
-- ❌ 禁止只在 `.col-action` 上设 text-align（部分浏览器会被覆盖）
+内容区大卡片容器（ContentCard 作为白卡容器使用时）表面规则：
 
-### 6.3 操作列行为映射
+| 属性 | v7.5 及之前 | **v7.6（当前）** |
+|------|-------------|----------------|
+| `border` | `1px solid hsl(var(--gray-line))` | **`none`（去掉）** |
+| `box-shadow` | `0 1px 2px rgba(0,0,0,0.04)` 或 `shadow-card` | **`var(--shadow-sm)` = `0 1px 2px rgba(0,0,0,0.05)`** |
+| `border-radius` | `var(--radius-lg)` = 12px | 保持不变 |
+| `background` | `hsl(var(--card))` | 保持不变 |
 
-| 操作      | 触发     | 前置       | 二次确认        | 目标              | 返回行为                             |
-| --------- | -------- | ---------- | --------------- | ----------------- | ------------------------------------ |
-| 查看/管理 | 点链接   | —          | 否              | DetailPage        | 返回列表保持筛选+分页                |
-| 编辑      | 点按钮   | —          | 否              | FormPage / Drawer | 保存成功返回列表 + Toast「保存成功」 |
-| 删除      | 点按钮   | 资源已停止 | 是(三级 Dialog) | Dialog 确认       | 确认后刷新 + Toast「删除成功」       |
-| 更多      | Dropdown | —          | 按操作分级      | Dropdown 菜单     | 选择子操作                           |
+### 参考 CSS
 
----
+```css
+.card,
+.card-wrapper {
+  background: hsl(var(--card));
+  border-radius: var(--radius-lg);
+  /* v7.6：去掉 1px border，使用最弱阴影 */
+  box-shadow: var(--shadow-sm);
+  overflow: hidden;
+}
+```
 
-## 8. 主区对齐规则(硬约束 — 最容易不稳定的点)
+### 禁止项
 
-opentrek 主区由 `OpPageContainer` 提供 — 外层 `py-5 pr-5`(无左 padding,sidebar 自带 20px 间隙) + 内嵌**无边框白底大 Card**(`bg-card rounded-2xl p-6`)承载 PageHeader / ActionToolbar / DataTable / Pagination。水平 padding 分层模型:
+- ❌ 禁止 `border: 1px solid hsl(var(--gray-line))`（v7.6 去线框后不再需要）
+- ❌ 禁止硬编码 `box-shadow: 0 1px 2px rgba(0,0,0,0.04)`（一律走 `var(--shadow-sm)`）
+- ❌ 禁止使用 `shadow-DEFAULT` / `shadow-md` 等更强阴影（会造成表面过重）
+- ❌ 禁止同时使用 `border` + `shadow`（v7.6 为二选一关系，仅保留 `shadow`）
 
-- **OpPageContainer 外层**:`py-5 pr-5`(灰底主区 ↔ 白卡的间隙;左侧贴 sidebar 不留 padding)
-- **OpPageContainer 内白卡 padding = 24px**(`p-6`):提供白卡内缘 ↔ 非 Table 子组件的呼吸 — **由容器统一管,不要在 PageHeader / Toolbar 上再加 paddingX**
-- **Table 中间列 padding = 12px**(左右 12+12=24,列间 24px)
-- **Table 首列 padding-left = 20px**(额外缩进让 checkbox 与白卡内缘有呼吸)
-- **Table 末列 padding-right = 20px**
+### 不适用场景（依然使用 border）
 
-| 组件                                                    | 水平 padding        | 起始 X              |
-| ------------------------------------------------------- | ------------------- | ------------------- |
-| OpPageContainer 外层                                    | `pr-5`(右 20,左 0)  | PageShell main 外缘 |
-| OpPageContainer 内白卡                                  | **24px**(`p-6`)     | 白卡内缘            |
-| PageHeader / ActionToolbar / BulkActionBar / Pagination | **0**               | 白卡内缘 + 24       |
-| Table 中间列 td                                         | 12px                | —                   |
-| Table 首列 td                                           | padding-left: 20px  | 白卡内缘 + 44       |
-| Table 末列 td                                           | padding-right: 20px | 白卡右内缘 - 44     |
+- 浮层类：Dropdown / Popover / Select content / Tooltip
+- 业务卡片列表项 (item-card / GenericCard)
+- @teamix-evo/ui 默认 Card（未作为内容区白卡容器使用时）
 
-### 禁止项
+> Token 定义：`rules/design-tokens.json` · `componentSpacing.Card.surface`
+> 组件规格：`rules/component-specs.json` · `C7-Card.contentCardOverride`
 
-- ❌ 在 OpPageContainer 主区再叠一层 `<Card>` — 容器已经内置大白卡,嵌套违反白卡单例
-- ❌ 在 PageHeader / ActionToolbar / Pagination 上重复设 paddingX(会与 OpPageContainer 内白卡的 `p-6` 叠加为 48px)
-- ❌ Table 中间列 padding 不为 12px
-- ❌ Table 首/末列 padding 不为 20px
-- ❌ 用 `px-4` `px-6` 字面量直接套子组件 — 用 `px-3 first:pl-5 last:pr-5` 让 Table 自己分配
-- ❌ 在 OpPageContainer 内白卡与子组件间插入额外 paddingX 包裹层
-
-### 验证
+---
 
-1. PageHeader / ActionToolbar / Pagination 起始 X = OpPageContainer 内白卡左内缘 + 24
-2. Table 首列(checkbox)内容 X = OpPageContainer 内白卡左内缘 + 44
-3. Table 相邻中间列内容间距 = 24
+## 5. 嵌套约束
+
+| 父子关系 | 状态 | 说明 |
+|----------|------|------|
+| PageContainer → ContentWrapper | ALLOW | 右侧内容大容器（必需） |
+| ContentWrapper → Card(白卡容器) | ALLOW | 白色卡片容器，包裹所有业务内容（必需） |
+| Card(白卡容器) → PageHeader | ALLOW | 标准结构 |
+| Card(白卡容器) → ActionToolbar | ALLOW | 操作工具栏 |
+| Card(白卡容器) → DataTable | ALLOW | 核心组件 |
+| Card(白卡容器) → CardGrid | ALLOW | 卡片列表 |
+| Card(白卡容器) → ViewToggle | ALLOW | 视图切换 |
+| Card(白卡容器) → AdvancedFilterPanel | ALLOW | 高级筛选面板 |
+| Card(白卡容器) → Pagination | ALLOW | 分页控件 |
+| ContentWrapper → PageHeader / ActionToolbar / DataTable / CardGrid / Pagination | FORBID | 业务组件必须经过白卡容器包裹 |
+| Card(白卡容器) → Card(白卡容器) | FORBID | 白卡容器为单例，禁止嵌套 |
+| ActionToolbar → SearchCombo | ALLOW | 搜索组合 |
+| CardGrid → ItemCard | ALLOW | 业务卡片（v7.3 起详见 `patterns/card-list.md` §9.1） |
+| ItemCard → CardActionBar | ALLOW | 卡片操作栏，三态：hover-slidebar / hover-fade / always-visible（v7.3 详见 `patterns/card-list.md` §9.3） |
+| DataTable → Pagination | ALLOW | 分页控件 |
+| DataTable → Dialog | WARN | 确认弹窗由全局状态管理 |
+| DataTable → Form | FORBID | 表格内不应直接嵌套完整表单 |
+| Sidebar → DescriptionList | FORBID | 描述列表不应嵌套在侧边栏 |
 
 ---
 
-## 9. 状态-操作模式
+## 6. 共享规则引用
 
-### 8.1 元规则
+以下规范为多个子类型共用，提取到 `_shared/` 目录：
 
-- 每个状态必须定义操作可用性矩阵
-- 禁用样式统一 `opacity-45 pointer-events-none`
-- 混合状态时批量按钮禁用，hover 提示原因
-- 异步操作必须有 Toast + 列表刷新机制
+| 共享规则 | 路径 | 被引用子类型 |
+|----------|------|-------------|
+| 表格列元规则 | `_shared/column-meta-rules.md` | standard, l2-sidebar, expandable, drawer, view-toggle（列表视图） |
+| 操作列规范 | `_shared/action-column-spec.md` | standard, l2-sidebar, expandable, drawer, view-toggle（列表视图） |
+| 状态-操作模式 | `_shared/state-action-pattern.md` | standard, l2-sidebar, expandable, drawer, pure-card, standard-card, view-toggle |
+| 业务卡片三件套规格（v7.3 下沉） | `patterns/card-list.md` §9（ItemCard/CardGrid/CardActionBar 完整规格） | pure-card, standard-card, view-toggle（均路由到 patterns/card-list.md） |
 
-### 8.2 操作确认分级
+子类型文件按需要引用对应共享文件。
 
-| 级别                 | 适用                 | 确认方式              |
-| -------------------- | -------------------- | --------------------- |
-| **一级**（可逆）     | 查看、编辑、远程连接 | 直接执行              |
-| **二级**（影响状态） | 启动、停止、重启     | Dialog 确认           |
-| **三级**（不可逆）   | 删除                 | Dialog + 输入确认文本 |
+## 7. 产品配置引用
 
-### 8.3 异步反馈
+> 具体列定义、状态机、业务场景按产品隔离，存放在 `products/{产品}/` 目录。
+> AI 读取时需根据目标产品加载对应配置文件。
 
-| 操作     | Toast 文案                | 列表         |
-| -------- | ------------------------- | ------------ |
-| 状态变更 | "操作已提交"              | 轮询状态     |
-| 删除     | "删除已提交"              | 移除行或刷新 |
-| 批量     | "批量操作已提交，共 N 条" | 轮询         |
+| 产品类型 | 列定义 | 状态机 | 业务映射 |
+|----------|--------|--------|---------|
+| ECS | `products/ecs/columns.json` | `products/ecs/states.json` | `products/ecs/mapping.json` |
+| PolarDB | `products/polar-db/columns.json` | `products/polar-db/states.json` | `products/polar-db/mapping.json` |
+| Cloud-Catalog | `products/cloud-catalog/columns.json` | `products/cloud-catalog/states.json` | — |
+| AI Gateway | `products/ai-gateway/columns.json` | `products/ai-gateway/states.json` | `products/ai-gateway/mapping.json` + `cards.json`（v7.2 新增，卡片视图 slot 绑定） |
 
-### 8.4 页面间导航交互
-
-- **操作列「查看/管理」** → DetailPage(页面跳转);面包屑返回,保持筛选+分页
-- **操作列「编辑」** → FormPage 或 Drawer(跳转/侧滑);保存/取消返回列表,保存附 Toast
-- **创建操作** → FormPage(页面跳转);创建成功/取消返回列表
-- **搜索执行** → 当前列表(数据刷新);重置到第 1 页
-- **筛选条件变更** → 当前列表(数据刷新);重置到第 1 页,保持筛选条件
+**读取规则**：
+1. 根技能确定页面类型 → Phase ①
+2. 子技能匹配子类型 → Phase ②
+3. 根据目标产品加载 `products/{产品}/` 下对应配置文件 → Phase ②.5
+4. 元规则（列应该有显隐规则/拖拽/排序） + 产品配置（具体列名/宽度/状态） → Phase ③ 生成 HTML
 
 ---
 
-## 10. 嵌套约束
-
-| 父子关系                                                                                                                       | 状态                                                                    |
-| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
-| PageShell(background="muted", sidebar=OpSidebar) → OpPageContainer(header=PageHeader) → ActionToolbar / DataTable / Pagination | ALLOW                                                                   |
-| OpPageContainer 内大白卡 → 再嵌一层 `<Card>` 包业务组件                                                                        | **FORBID**(OpPageContainer 已内置大白卡,嵌套违反白卡单例)               |
-| ActionToolbar → SearchCombo                                                                                                    | ALLOW                                                                   |
-| CardGrid → ItemCard → CardActionBar                                                                                            | ALLOW(卡片网格内每个 ItemCard 是局部小卡 — 业务子区域级,非主区白卡嵌套) |
-| DataTable → Pagination                                                                                                         | ALLOW                                                                   |
-| DataTable → Form                                                                                                               | **FORBID**(用 Drawer 触发)                                              |
-
----
+## 规范引用
 
-## 11. 禁止项
+- **读取路径**：见根技能 `../../SKILL.md` §4.5 四阶段读取决策树
+  - 阶段①：`page-types.json` + `business-mapping.json`
+  - 阶段②：`page-frame.json` + `layout-rules.json` + `page-flow.json` + `_shared/search-combo-spec.md`；卡片子类型 (pure-card / standard-card / view-toggle) 追加读取 `patterns/card-list.md`（v7.3 起为三件套唯一规范来源）
+  - 阶段②.5：`products/{产品}/columns.json` + `states.json`（v6.2 新增）
+  - 阶段③（生成 HTML 时）：`design-tokens.json` + `design-tokens.css` + `styling.json` + `../boundaries.md` + `../foundations.md`
 
-| 禁项                   | 原因                                |
-| ---------------------- | ----------------------------------- |
-| Form 直接出现在内容区  | 应通过 Dialog/Drawer/FormPage 触发  |
-| Chart 出现在标准列表   | 图表归属 Dashboard                  |
-| 内联编辑               | 编辑必须通过 Drawer/Dialog/FormPage |
-| 拖拽排序               | 表格数据为服务端排序                |
-| 无限滚动               | B2B 管理场景需精确分页              |
-| 悬浮操作栏             | 遮挡数据，可发现性差                |
-| 右键菜单               | 移动端不兼容                        |
-| `hr` / section-divider | 间距通过 padding/margin 控制        |
+> `rules/design-tokens.css` 是设计 Token 的唯一真相源（:root 变量定义）：生成 HTML 原型时需将 :root 变量块嵌入页面 `<style>` 标签；生成 React/TSX 需确保项目已通过 `@import` 引入该 CSS 文件。
 
 ---
 
-## 12. 列表页特有自检
-
-- [ ] PageHeader / ActionToolbar / DataTable / Pagination 嵌套结构正确
-- [ ] Card 内统一左右 padding 24px（除 Table 列）
-- [ ] 子类型组件正确（standard 用 DataTable，pure-card 用 CardGrid）
-- [ ] SearchCombo 位置正确（间距 20px）
-- [ ] 操作列水平对齐左对齐
-- [ ] 状态-操作矩阵在所有状态下正确
-- [ ] 二次确认按级别正确（启动/停止 = Dialog；删除 = 输入确认）
-- [ ] 批量操作按钮：选中 ≥1 行显示，混合状态禁用
-- [ ] 搜索：回车执行、维度切换清空、FilterTag 展示
-- [ ] 分页：保持筛选 + "共 N 条"
-- [ ] 边界：空数据 Empty + 加载 Loading + 错误 ErrorState
+## 验证清单 (Validation Checklist)
+
+> **通用检查项**（布局分区/颜色Token/间距/字体/尺寸/禁用样式/异步操作/空数据/加载中）见根技能 `../../docs/validation-workflow.md` 验证清单。此处仅列出列表页特有检查项。
+
+| 检查项 | 检查点 | 目标 |
+|--------|--------|------|
+| 嵌套结构 | PageContainer → ContentWrapper → Card(白卡容器) → PageHeader/ActionToolbar/DataTable/Pagination | 100% |
+| Card 内统一左右内边距 | PageHeader/ActionToolbar/DataTable/Pagination 在 Card 内左右 padding 均为 24px | 100% |
+| 必需组件 | PageHeader、ActionToolbar、Pagination + 子类型组件（DataTable/CardGrid） | 100% |
+| 禁止组件 | 无内联编辑、拖拽排序、无限滚动、悬浮操作栏、右键菜单 | 0 个 |
+| 子类型组件 | 按子类型路由到正确组件（DataTable 或 CardGrid） | 正确 |
+| 操作可用性 | 状态-操作矩阵匹配 | 所有状态正确 |
+| 二次确认 | 启动/停止/重启 Dialog确认，删除需输入确认 | 正确 |
+| 批量操作 | 选中≥1行显示、混合状态禁用、异步处理 | 正确 |
+| 搜索交互 | 回车执行、下拉切换维度、FilterTag 展示 | 正确 |
+| 分页 | 默认条数、保持筛选、"共N条" | 正确 |