@teamix-evo/skills 0.11.0 → 0.12.0

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

@@ -4,7 +4,8 @@
 > 覆盖三种卡片视图子类型：**pure-card** / **standard-card** / **view-toggle**
 > 核心组件：**CardGrid** > **ItemCard** × N → **CardActionBar**
 > 全局规则继承：[L1 框架](../../../rules/page-frame.json) / [布局模式](../../../rules/layout-rules.json) / [CRUD 流转](../../../rules/page-flow.json) / [SearchCombo](../_shared/search-combo-spec.md)
-> **本文件为业务卡片三件套（ItemCard/CardGrid/CardActionBar）的唯一规范来源**（v7.3 起：`rules/card-component.json` 已废止，所有规格下沉至此 §9）
+> **业务卡片三件套（ItemCard/CardGrid/CardActionBar）完整规格** → [_shared/item-card-spec.md](../_shared/item-card-spec.md)
+> **OpenTrek 业务页面组合规则** → [card-list-opentrek.md](./card-list-opentrek.md)
 
 ---
 
@@ -13,7 +14,7 @@
 | 术语 | 定位 | 别名 | 规范来源 |
 |------|------|------|------|
 | **ContentCard** | 页面主内容**白色容器**，padding 24px，每页**单例** | 白卡容器 / shadcn-Card | `rules/component-specs.json` C7-Card |
-| **ItemCard** | CardGrid 内的**单个数据项卡片**，可重复 N 次 | 业务卡片 / 卡片视图列表项 | 本文件 §9.1 |
+| **ItemCard** | CardGrid 内的**单个数据项卡片**，可重复 N 次 | 业务卡片 / 卡片视图列表项 | [item-card-spec.md §1](../_shared/item-card-spec.md) |
 
 > **规则**：本 pattern 及任何引用本 pattern 的文档，禁止只写 "Card"，必须显式使用 `ContentCard` 或 `ItemCard` 区分。
 
@@ -36,7 +37,7 @@
 | Pagination 默认条数 | 12 | 12 | 10（卡片）/ 10（列表） |
 | 其他特殊 | ToggleGroup 胶囊筛选位于 ActionToolbar 右侧 | 同 pure-card | DataTable + BulkActionBar 与 CardGrid 同级，由 ViewToggle 切换可见 |
 
-> **density / iconStyle / cardGridPreset / actionBarMode 的详细规格见本文件 §9 三件套完整规范。**
+> **density / iconStyle / cardGridPreset / actionBarMode 的详细规格见 [item-card-spec.md](../_shared/item-card-spec.md)。**
 
 ---
 
@@ -67,24 +68,50 @@
 > Sidebar 由 [`page-frame.json`](../../../rules/page-frame.json) L1 自动继承（TWO_COL 显示 / SINGLE_COL 隐藏），本 pattern 不重复声明。
 > ContentCard 内左右对齐遵循 [分层 padding 模型 v7.5](../SKILL.md#5-1-card-内左右对齐稳定规则硬约束)（Card.paddingX 20px 唯一来源）。
 
+### 2.1 ActionToolbar 布局细则（截图实证补充）
+
+> 8 张截图验证的 ActionToolbar 三段式布局：
+
+```
+┌─ ActionToolbar (flex, nowrap, align-items: center, gap: 8px) ─────────────────┐
+│ .left-actions          .search-combo                .right-tools (ml: auto)   │
+│ [+ 新建xx] [导入]      [搜索框🔍]                  [全部|类型A|类型B|类型C]    │
+│ ← gap 8px →            ← margin-left 20px →        ← margin-left: auto →     │
+└───────────────────────────────────────────────────────────────────────────────┘
+```
+
+| 区域 | 组件 | 规格 | UI 组件引用 |
+|------|------|------|-------------|
+| left-actions | 主操作按钮 | Primary 最多 1 个，其余 Secondary/Ghost | `components/button` → `Button` |
+| search-combo | 搜索输入框 | 与 left-actions 间距 20px | `components/input` → `Input` + `components/select` |
+| **right-tools** | **ToggleGroup 筛选** | margin-left: auto 推到右侧；Tab 样式；选中 = `var(--primary)` + 底部 2px 线 | `components/toggle-group` → `ToggleGroup` |
+
+**ToggleGroup 筛选交互规范**（截图提取）：
+- 高度: 32px（与搜索框等高）
+- 选项 font-size: 13px
+- 选中态: color `var(--primary)` + border-bottom 2px solid `var(--primary)`
+- 未选中态: color `var(--gray-secondary)`；hover → `var(--gray-primary)`
+- 首项固定为"全部"（不可省略）
+- 选项数量: 3-7 个为宜；超过 7 个考虑用 Dropdown 收纳
+
 ---
 
 ## 3. 必需组件清单
 
-| 组件 | 来源规范 | 子类型适用 |
-|------|----------|------------|
-| Sidebar | rules/page-frame.json (L1 框架自动继承) | standard-card / view-toggle |
-| ContentCard | rules/component-specs.json C7-Card | 全部 |
-| PageHeader | rules/common-components.json | 全部 |
-| ActionToolbar | — | 全部 |
-| SearchCombo | _shared/search-combo-spec.md | 全部 |
-| ToggleGroup（胶囊筛选 / ViewToggle 复用） | rules/common-components.json | 全部（ViewToggle 仅 view-toggle 必需） |
-| **CardGrid** | **本文件 §9.2** | 全部 |
-| **ItemCard** × N | **本文件 §9.1** | 全部 |
-| **CardActionBar** | **本文件 §9.3** | 全部 |
-| Pagination | rules/common-components.json | 全部 |
-| DataTable | _shared/column-meta-rules.md + action-column-spec.md | view-toggle 切换列表视图时 |
-| BulkActionBar | — | view-toggle 列表视图 |
+| 组件 | 来源规范 | UI 组件库引用 | 子类型适用 |
+|------|----------|--------------|------------|
+| Sidebar | rules/page-frame.json (L1 框架自动继承) | `components/sidebar` | standard-card / view-toggle |
+| ContentCard | rules/component-specs.json C7-Card | `components/card` → `Card` + `CardContent` | 全部 |
+| PageHeader | rules/common-components.json | `components/page-header` → `PageHeader` + `PageHeaderHeading` | 全部 |
+| ActionToolbar | — | 组合组件（见 [opentrek §5.2](./card-list-opentrek.md#52-组件引用清单)） | 全部 |
+| SearchCombo | _shared/search-combo-spec.md | `components/input` → `Input` + `components/select` → `Select` | 全部 |
+| ToggleGroup（胶囊筛选 / ViewToggle 复用） | rules/common-components.json | `components/toggle-group` → `ToggleGroup` + `ToggleGroupItem` | 全部 |
+| **CardGrid** | [item-card-spec.md §2](../_shared/item-card-spec.md#2-cardgrid卡片网格) | CSS Grid 实现（无对应 UI 组件） | 全部 |
+| **ItemCard** × N | [item-card-spec.md §1](../_shared/item-card-spec.md#1-itemcard业务卡片) | `components/card` → `Card` + `CardHeader` + `CardContent` + `CardFooter` | 全部 |
+| **CardActionBar** | [item-card-spec.md §3](../_shared/item-card-spec.md#3-cardactionbar卡片操作栏) | 组合组件 | 全部 |
+| Pagination | rules/common-components.json | `components/pagination` → `Pagination` + 子组件 | 全部 |
+| DataTable | _shared/column-meta-rules.md + action-column-spec.md | `components/data-table` | view-toggle 切换列表视图时 |
+| BulkActionBar | — | 组合组件 | view-toggle 列表视图 |
 
 ---
 
@@ -116,7 +143,7 @@
 | ItemCard → ItemCard | FORBID | 业务卡片禁止嵌套 |
 | CardGrid → 任何非 ItemCard 子节点 | FORBID | Grid 仅承载业务卡片 |
 
-> 卡片组件级硬约束（hover/states/CSS 规则）见 §9。
+> 卡片组件级硬约束（hover/states/CSS 规则）见 [item-card-spec.md](../_shared/item-card-spec.md)。
 
 ---
 
@@ -199,353 +226,50 @@
 
 ---
 
-## 9. 业务卡片三件套完整规格【唯一规范来源】
-
-> 本节规格自 v7.3 起从 `rules/card-component.json` 下沉至此。`common-components.json` 中 ItemCard/CardGrid/CardActionBar 的 `specRef` 指向本节锚点。
-> 三件套用于列表页卡片视图；未来如 Dashboard / Workspace / Overview 需要复用，可直接引用本节锚点。
-
-### 9.1 ItemCard（业务卡片）
-
-- **level**: ORGANISM
-- **layer**: business
-- **shadcnComponent**: Card（基于白卡容器扩展）
-- **场景**：CardGrid 内的单个数据项卡片，含 Title/Description/Field/Supplementary/ActionBar 等 slot，可重复多次出现。
-
-#### 9.1.1 variants 变体
-
-| 维度 | 选项 | 默认 | 说明 |
-|------|------|------|------|
-| density | minimal / standard / complex | standard | 信息密度，按 §4 选型矩阵决定 |
-| iconStyle | avatar / tile | avatar | avatar=32×32 圆角（pure-card / standard-card）；tile=40×40 大方块（view-toggle） |
-| titleFontSize | 14px / 16px | — | iconStyle=avatar → 14px/500；iconStyle=tile → 16px/500 |
-
-**iconStyle.avatar 详细**：
-- size: 32×32（常规/复杂）/ 24×24（极简）
-- shape: 圆角矩形 `var(--input-radius)`
-- fallback: 首字母色块 + Glossy 光泽（见 §9.1.6）
-
-**iconStyle.tile 详细**：
-- size: 40×40
-- shape: 大方块（直角或微圆角）
-- fallback: 纯图标，无首字母回退
-
-#### 9.1.2 slots（5 个 slot 区，按 density 决定使用）
-
-| Slot | minimal | standard | complex | 元素与样式 |
-|------|---------|----------|---------|-----------|
-| **CardTitleRow** | 必需 | 必需 | 必需 | icon + title + [badge] + [statusDot] |
-| **CardDescriptionRow** | 禁止 | 必需 | 必需 | text（standard: 12px/lineClamp 1；complex: 14px/lineClamp 2）；color: `var(--gray-tertiary)` |
-| **CardFieldRow** | 禁止 | 0-2 行（可选） | 2-4 行（可选） | fieldIcon(12×12) + fieldLabel(12px) + fieldValue(14px standard / 12px complex) |
-| **CardSupplementaryRow** | 1 行（必需） | 0-1 行（可选） | 1 行（必需） | 元信息：创建人/时间/地域；icon(12×12) + label(12px) + value(12px) |
-| **CardActionBar** | 必需 | 必需 | 必需 | 通过 slot 引用（见 §9.3） |
-
-**CardTitleRow 元素**：
-- icon: minimal=24×24；standard=Avatar 32×32(avatar) / Icon 40×40(tile)；complex=Avatar 32×32；borderRadius `var(--input-radius)`；flex-shrink 0
-- title: 由 variants.titleFontSize 决定；font-weight 500；color `var(--gray-primary)`；单行 truncate
-- badge（可选）: 10px / padding 1px 4px / border-radius 2px；用于「企业版」「Beta」标识
-- statusDot（可选）: 6px 圆点；位置标题尾部或卡片右上角
-
-**CardDescriptionRow CSS**：
-```css
-.card-desc {
-  overflow: hidden;
-  text-overflow: ellipsis;
-  display: -webkit-box;
-  -webkit-line-clamp: N;        /* standard=1 / complex=2 */
-  -webkit-box-orient: vertical;
-}
-```
-
-#### 9.1.3 rowGap（slot 间垂直间距，仅 standard 模式）
-
-| from → to | gap |
-|-----------|-----|
-| CardTitleRow → CardDescriptionRow | 4px |
-| CardDescriptionRow → CardFieldRow | 8px |
-| CardFieldRow → CardSupplementaryRow | 4px |
-
-#### 9.1.4 structureByDensity（density 结构概览）
-
-| density | rowsAscii | 高度 | actionBarMode |
-|---------|-----------|------|----------------|
-| minimal | CardTitleRow → CardSupplementaryRow → CardActionBar | ~100px | hover-fade |
-| standard | CardTitleRow → CardDescriptionRow → CardFieldRow(0-2) → CardSupplementaryRow(0-1) → CardActionBar | ~160px | hover-slidebar（默认）/ always-visible（view-toggle 覆写）|
-| complex | CardTitleRow → CardDescriptionRow(line-clamp:2) → CardFieldRow×2-4 → CardSupplementaryRow → CardActionBar(1-2行) | 240px+ | hover-slidebar |
-
-#### 9.1.5 states（卡片整体状态）
-
-| state | border | background | shadow | actionBar |
-|-------|--------|------------|--------|-----------|
-| default | 1px solid `var(--gray-border)` | `var(--card)` | none | 由 actionBarMode 决定：hover-* 隐藏 / always-visible 常驻 |
-| hover | 1px solid `var(--primary)` + breathing | `var(--card)` | `var(--shadow-sm)` | 可见 |
-| focus | 2px solid `var(--primary)` | `var(--card)` | `var(--shadow-sm)` | 可见 |
-| disabled | 1px solid `var(--gray-border)` | `var(--gray-fill)` | none | 隐藏 |
-
-**hover.breathingBorder CSS**：
-```css
-@keyframes breathing { 0%,100% { opacity:0.5 } 50% { opacity:1 } }
-.card-hover-breathing { animation: breathing 2s ease-in-out infinite; }
-```
-应用在 hover 状态下的 border。
-
-**clickBehavior**：
-- 卡片主体点击：跳转 DetailPage 或进入编辑
-- ActionBar 点击：执行对应 action，事件 `stopPropagation` 不影响卡片 hover
-
-#### 9.1.6 avatarPreset（色块头像系统，iconStyle=avatar 且无图片时）
-
-**colorClasses**（9 种）：`bg-primary` / `bg-success` / `bg-type-mcp` / `bg-warning` / `bg-data-8` / `bg-data-1` / `bg-destructive` / `bg-brand-3` / `bg-data-4`
-
-**fallbackPriority**：
-1. avatar 字段为有效颜色 class → 色块 + 首字母
-2. avatar 字段为有效图片 URL → `<img>`
-3. avatar 字段为空 → `name.charAt(0)` hash 到预设色 + 首字母
-
-**blockStyle**：
-- size: 32×32
-- borderRadius: `var(--input-radius)`
-- textColor: `#fff`
-- fontWeight: 600
-- fontSize: 14px
-- content: `name.charAt(0).toUpperCase()`
-
-**glossy 光泽 CSS**（色块右侧叠加半透明白色渐变）：
-```css
-.avatar-gloss {
-  position: absolute;
-  width: 18px; height: 32px;
-  right: 0; top: 0;
-  background: linear-gradient(180deg, rgba(255,255,255,0.4) 0%, rgba(255,255,255,0.2) 40%, transparent 100%);
-  pointer-events: none;
-}
-```
-
-#### 9.1.7 constraints（硬约束）
-
-- 标题：必须包含，禁止无标题卡片
-- 标题长度：单行省略 (truncate)
-- 描述长度：standard 1 行 / complex 最多 2 行 (`-webkit-line-clamp: 2`)
-- 卡片嵌套：禁止业务卡片嵌套业务卡片（最多 1 级）
-- 样式一致性：同一页面内 ItemCard 的 density + iconStyle 必须保持一致
-- 深色模式：所有图标使用 mask-image 方案（见 [boundaries.md I1-I4](../../../boundaries.md)）
-
-#### 9.1.8 tokens（设计 token 映射）
-
-| 用途 | token |
-|------|-------|
-| background | `--card` |
-| border | `--gray-border` |
-| borderHover | `--primary` |
-| shadowHover | `--shadow-sm` |
-| radius | `--radius-lg` (12px) |
-| iconRadius | `--input-radius` (8px) |
-| titleColor | `--gray-primary` |
-| fieldColor | `--gray-secondary` |
-| descColor | `--gray-tertiary` |
-| disabledBg | `--gray-fill` |
-| transitionDuration | `--duration-normal` (200ms) |
-| transitionEasing | `--easing-ease` |
-
----
-
-### 9.2 CardGrid（卡片网格）
-
-- **level**: ORGANISM
-- **layer**: business
-- **shadcnImpl**: null
-- **场景**：承载多个 ItemCard，使用 CSS Grid `auto-fill` + `minmax` 自动响应式列数。
-
-#### 9.2.1 props
-
-| prop | 取值 | 说明 |
-|------|------|------|
-| minWidth | 必须引用 `var(--card-grid-min-*)` | 最小列宽（H2 修复，禁止字面量） |
-| gap | `var(--card-gap)` 默认 16px | 卡片间距 |
-| alignContent | literal: `'start'` | 防止卡片拉伸变形 |
-| children | `ItemCard[]` | 仅承载业务卡片 |
-
-#### 9.2.2 CSS 实现
-
-```css
-.card-grid {
-  display: grid;
-  grid-template-columns: repeat(
-    auto-fill,
-    minmax(var(--card-grid-min, var(--card-grid-min-standard)), 1fr)
-  );
-  gap: var(--card-gap, 16px);
-  align-content: start;
-}
-```
-
-#### 9.2.3 presets（4 套预设；pagination 已移除，真相源回归 §1 矩阵）
-
-| preset | minWidth | iconStyle | density | usedBy |
-|--------|----------|-----------|---------|--------|
-| **compact** | `var(--card-grid-min-compact)` (240px) | avatar | minimal | pure-card / standard-card |
-| **standard** | `var(--card-grid-min-standard)` (300px) | avatar | standard | pure-card / standard-card |
-| **feature** | `var(--card-grid-min-feature)` (360px) | avatar | complex | pure-card / standard-card |
-| **comfortable** | `var(--card-grid-min-comfortable)` (320px) | tile | standard | view-toggle |
-
-> Token 定义见 `rules/design-tokens.css`。
-
-#### 9.2.4 responsive（参考列数，由 auto-fill 自动计算，无需手写断点）
-
-| viewport | columns |
-|----------|---------|
-| ≥1400px | 4 |
-| 1080-1400px | 3 |
-| 768-1080px | 2 |
-| <768px | 1 |
-
-#### 9.2.5 constraints（硬约束）
-
-- 禁止手动写 `grid-template-columns` 字面量（必须用 `minmax + var(--min-width)`）
-- 禁止 `alignContent: stretch`（会导致卡片高度被拉伸变形）
-- 禁止在 CardGrid 与 ItemCard 之间插入额外 wrapper
-
----
-
-### 9.3 CardActionBar（卡片操作栏）
-
-- **level**: MOLECULAR
-- **layer**: business
-- **shadcnImpl**: null
-- **场景**：ItemCard 底部的操作栏 — 滑条式 (SlideBar) 设计，白底 + 主要文字色 + 等分宽度（v7.3.1 从主色底调整为白底以提升可读性与表单化一致性）。
-
-#### 9.3.1 props
-
-| prop | 取值 | 说明 |
-|------|------|------|
-| actions | `Array<{ label, onClick, destructive? }>` | 操作列表 |
-| mode | `'hover-slidebar' \| 'hover-fade' \| 'always-visible'` | 三态，默认由 ItemCard.density 决定，pattern 可覆写 |
-| rows | 1 \| 2 | complex 模式可分行 |
-
-#### 9.3.2 containerSpec（容器规格）
-
-```css
-.card-action-bar {
-  position: absolute;
-  bottom: 0; left: 0; right: 0;
-  background: var(--card);                 /* v7.3.1 白底 */
-  border-top: 1px solid var(--gray-line);  /* v7.3.1 顶部分割线代替主色底边 */
-  display: flex;
-  z-index: 2;
-}
-```
-
-> **硬约束**：
-> - 禁止撑开卡片高度（必须 `position: absolute`）
-> - 背景色与 ContentCard 保持一致（`var(--card)`），全局调整背景时不需修改本节
-
-#### 9.3.3 actionButtonSpec（按钮规格）
-
-| 属性 | 值 |
-|------|---|
-| flex | 1（等分宽度） |
-| padding | 8px |
-| text-align | center |
-| color | `var(--gray-primary)`（v7.3.1 主要文字色） |
-| font-size | 13px |
-| font-weight | 500 |
-| cursor | pointer |
-| border-right | `1px solid var(--gray-line)`（v7.3.1 按钮间分隔为浅分割线） |
-| last-child | border-right: none |
-| hover-bg | `var(--gray-fill)`（v7.3.1 浅灰样式 hover） |
-| hover-color | `var(--primary)`（v7.3.1 hover 文字高亮为主色，提高可交互发现性） |
-
-**destructive 按钮**（醒目警示，保留原色机制）：
-- background: `transparent`（默认跟随白底）
-- color: `var(--destructive)`（红色文字表警示）
-- hover-bg: `var(--destructive-bg)`（浅红背景 #FEF2F2）
-- hover-color: `var(--destructive)`（保持红色）
-- 位置：始终放在最后
-
-#### 9.3.4 modes 实现表（三态完整 CSS，名称与 ItemCard.structureByDensity.actionBarMode 完全一致）
-
-##### hover-slidebar（默认；适用 standard / complex density）
-- trigger: 鼠标 hover 卡片
-- method: `transform: translateY(100%)` → `translateY(0)`
-- duration: 200ms / easing: ease
-- visual: 白底上滑，顶部 1px 浅灰分割线与上方内容区分
-
-```css
-.card-action-bar { transform: translateY(100%); transition: transform .2s ease; }
-.card:hover .card-action-bar { transform: translateY(0); }
-```
-
-> **禁止**：使用 `max-height`（触发 reflow，性能差）
-
-##### hover-fade（适用 minimal density）
-- trigger: 鼠标 hover 卡片
-- method: visibility + opacity 切换
-- duration: 200ms / easing: ease
-
-```css
-.card-action-bar { visibility: hidden; opacity: 0; transition: all .2s ease; }
-.card:hover .card-action-bar { visibility: visible; opacity: 1; }
-```
-
-> **禁止**：使用 `display: none`（会导致卡片高度变化）
-
-##### always-visible（view-toggle 子类型覆写）
-- trigger: 无需 hover，常驻底部可见
-- method: 静态显示，无动画
-
-```css
-.card-action-bar {
-  transform: none;
-  visibility: visible;
-  opacity: 1;
-  position: absolute;
-  bottom: 0;
-}
-```
-
-> **禁止**：跟随 hover 状态切换可见性
-
-#### 9.3.5 rowsRule（按钮行规则）
-
-**single（rows=1）**：
-- max: 4 个按钮
-- buttonGap: 8px
-- overflow: 操作 >5 个时，剩余进入「更多 ▾」Dropdown
-
-**double（rows=2）**：
-- row1: 高频操作（管理/编辑/详情等，≤4 个）
-- row2: 低频操作 + 「更多 ▾」（续费/导出/删除等）
-- buttonGap: 8px
-- rowGap: 4px
-
-#### 9.3.6 actionBehavior（操作触发后的页面流转，引用 page-flow.json crudFlow）
-
-| action | confirm | target | after |
-|--------|---------|--------|-------|
-| 查看/详情 | false | DetailPage | 返回保持筛选 |
-| 编辑 | false | FormPage / Sheet | 保存后返回原页 |
-| 导出 | false | 文件下载 | — |
-| 删除 | Dialog 二次确认（level3）| API 调用 | 刷新列表 |
-
-#### 9.3.7 constraints（硬约束）
-
-- **样式**：禁止使用文字按钮或 Primary Button 替代滑条式样式
-- **背景**：`var(--card)` 白底（v7.3.1），与 ContentCard 保持一致；禁止使用主色底
-- **文字**：`var(--gray-primary)` 主要文字色（v7.3.1）；hover 转 `var(--primary)` 提示可点击
-- **动画**：仅使用本节 §9.3.4 三态（hover-slidebar / hover-fade / always-visible），禁止 `display:none` / `max-height`
-- **位置**：必须 `position: absolute; bottom: 0`，不撑开卡片高度
-- **危险操作**：`color: var(--destructive)` 红色文字（v7.3.1 从红底调整），始终放在最后；hover-bg `var(--destructive-bg)`
-- **按钮分隔**：相邻按钮使用 `1px solid var(--gray-line)` 右边框（v7.3.1 浅灰分割线），最后一个按钮无右边框
-
----
-
-## 10. 渲染流程（AI 生成卡片视图列表页时的引用顺序）
+## 9. 渲染流程（AI 生成卡片视图列表页时的引用顺序）
 
 1. **列表 pattern 路由** → 确定 layout（模式A-CARD / 模式D-CARD / 模式D + ViewToggle）
-2. **读取本文件** → 通过 §1 差异矩阵确认子类型；通过 §9 确认 ItemCard / CardGrid / CardActionBar 的 variant 与 preset
+2. **读取本文件** → 通过 §1 差异矩阵确认子类型；通过 [item-card-spec.md](../_shared/item-card-spec.md) 确认 ItemCard / CardGrid / CardActionBar 的 variant 与 preset
 3. **读取 `products/{产品}/cards.json`** → 取 ItemCard slot 的业务字段映射（§8）
 4. **读取 `products/{产品}/states.json`** → 取 actions 可用性（按状态机过滤）
-5. **渲染** CardGrid > ItemCard × N > slots（按 variant 决定 slot 启用/禁用，参考 §9.1.4 structureByDensity）
+5. **渲染** CardGrid > ItemCard × N > slots（按 variant 决定 slot 启用/禁用，参考 item-card-spec §1.4 structureByDensity）
 6. **应用** `rules/design-tokens.css` 变量（特别是 `--card-grid-min-*` / `--card-gap` / `--primary` / `--gray-*`）→ 完成样式
+7. **（OpenTrek 产品）** 额外读取 [card-list-opentrek.md](./card-list-opentrek.md) → 确认页面模式（OT-CL-1/2/3）与 Slot 变体（A-F）
+
+---
+
+## 10. UI 组件库完整引用索引
+
+> 以下为卡片视图列表页中涉及的所有 UI 组件库组件的统一引用表。
+> 基础路径：`packages/ui/src/components/`
+
+| 组件路径 | 导出组件 | 在卡片列表页中的用途 |
+|----------|----------|-------------------|
+| `components/page-shell` | `PageShell` | L1 级页面壳（header + sidebar + children） |
+| `components/sidebar` | `Sidebar`, `SidebarProvider`, `SidebarContent`, `SidebarHeader`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarGroupContent`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarMenuSub`, `SidebarMenuSubItem`, `SidebarMenuSubButton`, `SidebarSeparator`, `useSidebar` | 左侧导航菜单 |
+| `components/card` | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` | ContentCard 白卡容器 + ItemCard 业务卡片 |
+| `components/page-header` | `PageHeader`, `PageHeaderNav`, `PageHeaderContent`, `PageHeaderHeading`, `PageHeaderDescription`, `PageHeaderActions`, `PageHeaderFooter` | 页面标题区域 |
+| `components/button` | `Button`, `buttonVariants` | 创建/导入/辅助操作按钮 |
+| `components/input` | `Input`, `inputVariants` | 搜索输入框 |
+| `components/select` | `Select`, `SelectGroup`, `SelectValue`, `SelectTrigger`, `SelectContent`, `SelectLabel`, `SelectItem`, `SelectSeparator` | 下拉筛选/每页条数选择 |
+| `components/tabs` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `tabsListVariants` | 子视图 Tab 切换（variant='line'） |
+| `components/toggle-group` | `ToggleGroup`, `ToggleGroupItem` | 分类筛选标签组 |
+| `components/tag` | `Tag`, `CheckableTag`, `CheckableTagGroup`, `tagVariants`, `TAG_PALETTE_PRESETS` | 状态标签/分类筛选/装饰标签 |
+| `components/badge` | `Badge`, `badgeVariants` | 版本号/安全扫描/类型标识 |
+| `components/avatar` | `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarBadge`, `AvatarGroup`, `AvatarGroupCount` | 卡片图标（色块首字母/图片/图标） |
+| `components/pagination` | `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis` | 底部分页控件 |
+| `components/data-table` | `DataTable`（引用 `_shared/column-meta-rules.md`） | OT-CL-2 / view-toggle 列表视图 |
+| `components/alert` | `Alert` | 信息横幅（如"锁定的记忆不清理…"） |
+| `components/breadcrumb` | `Breadcrumb`, `BreadcrumbItem` | 面包屑导航（OT-CL-2） |
+| `components/empty` | `Empty`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, `EmptyContent` | 空数据状态 |
+| `components/skeleton` | `Skeleton` | 加载占位 |
+| `components/dropdown-menu` | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuSeparator`, `DropdownMenuLabel`, `DropdownMenuGroup` | 溢出操作菜单 |
+| `components/tooltip` | `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider` | 悬停提示 |
+| `components/separator` | `Separator` | 视觉分隔线 |
+| `components/dialog` | `Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter` | 删除确认弹窗 |
+| `components/sheet` | `Sheet`, `SheetContent`, `SheetHeader`, `SheetTitle`, `SheetDescription`, `SheetFooter` | 编辑抽屉 |
+| `components/filter-bar` | `FilterBar`, `FilterBarItem` | 高级筛选面板（OT-CL 扩展） |
+| `components/typography` | `Prose`, `Title`, `Paragraph`, `Text`, `Link` | 文本排版 |
 
 ---
 
@@ -553,6 +277,8 @@
 
 | 版本 | 变更 |
 |------|------|
-| v7.1 | 卡片规范从 `card-component-rules.md` 升格为 `rules/card-component.json` 业务组件 contract（ItemCard/CardGrid/CardActionBar 注册到 common-components.json） |
-| v7.2 | 三 patterns（pure-card-list / standard-card-list / view-toggle-list）合并为本文件；contract 修复 H1-H4 |
-| **v7.3** | **`rules/card-component.json` 废止**：完整规格下沉至本文件 §9（ItemCard / CardGrid / CardActionBar 的 variants / slots / states / hover / avatar / modes / constraints / tokens）；术语区分迁至 §0；cards.json Schema 迁至 §8.1；pageTypeMapping 迁至 §8.2；renderingFlow 迁至 §10。`common-components.json` 中 specRef 改指本文件锚点。 |
+| v7.1 | 卡片规范从 `card-component-rules.md` 升格为 `rules/card-component.json` 业务组件 contract |
+| v7.2 | 三 patterns 合并为本文件；contract 修复 H1-H4 |
+| **v7.3** | `rules/card-component.json` 废止：完整规格下沉至 `_shared/item-card-spec.md`；术语区分迁至 §0 |
+| **v7.4** | OpenTrek 业务规则独立为 `card-list-opentrek.md`：页面级组合模式（OT-CL-1/2/3）、6 种 ItemCard Slot 变体（A-F）、ActionToolbar 组合规则、FilterRow 筛选行规则、Avatar 色块映射、视觉稿标注参考 |
+| **v7.5** | 文件拆分重构：item-card-spec.md（387 行）+ card-list-opentrek.md（740 行）+ card-list.md（~280 行）；内部引用更新为跨文件锚点 |