@teamix-evo/skills 0.11.0 → 0.12.0

package/src/teamix-evo-design-opentrek/pages/list-page/_shared/item-card-spec.md

@@ -0,0 +1,386 @@
+# 业务卡片三件套完整规格（ItemCard / CardGrid / CardActionBar）
+
+> 本文件自 v7.3 起从 `rules/card-component.json` 下沉至此。`common-components.json` 中 ItemCard/CardGrid/CardActionBar 的 `specRef` 指向本文件。
+> 三件套用于列表页卡片视图；未来如 Dashboard / Workspace / Overview 需要复用，可直接引用本文件。
+> **规范唯一来源** — 禁止在其他文件中重复定义卡片三件套的 variants/slots/states/tokens。
+
+---
+
+## 1. ItemCard（业务卡片）
+
+- **level**: ORGANISM
+- **layer**: business
+- **UI 组件库引用**: `components/card` → `Card` + `CardHeader` + `CardTitle` + `CardDescription` + `CardContent` + `CardFooter`
+- **场景**：CardGrid 内的单个数据项卡片，含 Title/Description/Field/Supplementary/ActionBar 等 slot，可重复多次出现。
+
+### 1.1 variants 变体
+
+| 维度 | 选项 | 默认 | 说明 |
+|------|------|------|------|
+| density | minimal / standard / complex | standard | 信息密度，按选型矩阵决定 |
+| 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 光泽（见 §1.6）
+- **UI 组件库引用**: `components/avatar` → `Avatar` (size='default'=32px / size='sm'=24px) + `AvatarFallback`
+
+**iconStyle.tile 详细**：
+- size: 40×40
+- shape: 大方块（直角或微圆角）
+- fallback: 纯图标，无首字母回退
+- **UI 组件库引用**: `components/avatar` → `Avatar` (size='lg'=40px) + `AvatarFallback`
+
+### 1.2 slots（5 个 slot 区，按 density 决定使用）
+
+| Slot | minimal | standard | complex | 元素与样式 | UI 组件库引用 |
+|------|---------|----------|---------|-----------|--------------|
+| **CardTitleRow** | 必需 | 必需 | 必需 | icon + title + [badge] + [statusDot] | `Avatar` + `CardTitle` + `Badge` / `Tag` |
+| **CardDescriptionRow** | 禁止 | 必需 | 必需 | text（standard: 12px/lineClamp 1；complex: 14px/lineClamp 2）；color: `var(--gray-tertiary)` | `CardDescription` |
+| **CardFieldRow** | 禁止 | 0-2 行（可选） | 2-4 行（可选） | fieldIcon(12×12) + fieldLabel(12px) + fieldValue(14px standard / 12px complex) | 内联 span 元素 |
+| **CardSupplementaryRow** | 1 行（必需） | 0-1 行（可选） | 1 行（必需） | 元信息：创建人/时间/地域；icon(12×12) + label(12px) + value(12px) | 内联 span + `Tooltip` |
+| **CardActionBar** | 必需 | 必需 | 必需 | 通过 slot 引用（见 §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
+  - **UI 组件库引用**: `components/avatar` → `Avatar` + `AvatarFallback`
+- title: 由 variants.titleFontSize 决定；font-weight 500；color `var(--gray-primary)`；单行 truncate
+  - **UI 组件库引用**: `components/card` → `CardTitle`
+- **subName**（可选）: 12px / 400 / `var(--gray-tertiary)`；margin-top 2px 紧贴 title 下方；用于英文标识（如 "code-generator"/"self-improvement"）
+  - **UI 组件库引用**: 原生 `<span>` 或 `components/typography` → `Text`
+- badge（可选）: 10px / padding 1px 4px / border-radius 2px；用于「企业版」「Beta」标识
+  - **UI 组件库引用**: `components/badge` → `Badge` (variant='secondary' / 'outline')
+- **statusBadge**（可选）: 12px / borderless Tag / 紧跟 title 后 gap 8px；"启用" = `var(--success)` + `var(--success-bg)` / "禁用" = `var(--gray-tertiary)` + `var(--gray-fill)`
+  - **UI 组件库引用**: `components/tag` → `Tag` (variant='borderless', color='success'/'default')
+- **versionBadge**（可选）: 12px / 500 / `var(--gray-secondary)` / **right-aligned**（`margin-left: auto`）；用于版本号展示如 "v3.0.1"
+  - **UI 组件库引用**: 原生 `<span>` 或 `components/badge` → `Badge` (variant='outline')
+- statusDot（可选）: 6px 圆点；位置标题尾部或卡片右上角
+  - **UI 组件库引用**: `components/tag` → `Tag` (variant='status', status='success'/'error'/...)
+
+**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;
+}
+```
+- **UI 组件库引用**: `components/card` → `CardDescription`
+
+**CardFieldRow 元素与行内状态指示器**：
+- fieldIcon（可选）: 12-14px inline icon；color `var(--gray-tertiary)`
+  - **UI 组件库引用**: lucide-react 图标（12px size）
+- fieldLabel: 12px / `var(--gray-tertiary)` / 后跟中文冒号 "："
+- fieldValue: 12px / `var(--gray-secondary)`（纯文本）
+- **inlineStatus**（可选，替代 fieldValue）: 带色彩和图标的状态值
+  - **UI 组件库引用**: `components/tag` → `Tag` (variant='borderless', size='sm') 或内联 span
+
+**行内状态指示器样式表**（截图实证，出现在 Skills Hub 安全扫描/安装状态等字段）：
+
+| 状态值 | color token | icon (lucide 12px) | 用法 |
+|--------|-------------|-------|------|
+| "安全" | `var(--success)` | `shield-check` | 安全扫描通过 |
+| "有风险" | `var(--destructive)` | `alert-triangle` | 安全扫描异常 |
+| "已安装" | `var(--success)` | `check` | 安装完成 |
+| "有更新" | `var(--warning)` | `refresh-cw` | 有可用更新 |
+| "未安装" | `var(--gray-tertiary)` | 无 | 未安装状态 |
+
+```css
+/* CardFieldRow inline-status */
+.field-row { display: flex; align-items: center; gap: 4px; font-size: 12px; }
+.field-row__label { color: var(--gray-tertiary); white-space: nowrap; }
+.field-row__value { color: var(--gray-secondary); }
+.field-row__status { display: inline-flex; align-items: center; gap: 4px; font-weight: 500; }
+.field-row__status--success { color: var(--success); }
+.field-row__status--warning { color: var(--warning); }
+.field-row__status--danger  { color: var(--destructive); }
+```
+
+### 1.3 rowGap（slot 间垂直间距，仅 standard 模式）
+
+| from → to | gap |
+|-----------|-----|
+| CardTitleRow → CardDescriptionRow | 4px |
+| CardDescriptionRow → CardFieldRow | 8px |
+| CardFieldRow → CardSupplementaryRow | 4px |
+
+### 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 |
+
+### 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 | 隐藏 |
+| **selected** | **2px solid `var(--primary)`** | **`var(--card)`** | **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
+
+### 1.6 avatarPreset（色块头像系统，iconStyle=avatar 且无图片时）
+
+- **UI 组件库引用**: `components/avatar` → `Avatar` + `AvatarFallback`
+
+**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>` → 使用 `AvatarImage`
+3. avatar 字段为空 → `name.charAt(0)` hash 到预设色 + 首字母 → 使用 `AvatarFallback`
+
+**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;
+}
+```
+
+### 1.7 constraints（硬约束）
+
+- 标题：必须包含，禁止无标题卡片
+- 标题长度：单行省略 (truncate)
+- 描述长度：standard 1 行 / complex 最多 2 行 (`-webkit-line-clamp: 2`)
+- 卡片嵌套：禁止业务卡片嵌套业务卡片（最多 1 级）
+- 样式一致性：同一页面内 ItemCard 的 density + iconStyle 必须保持一致
+- 深色模式：所有图标使用 mask-image 方案（见 [boundaries.md I1-I4](../../../boundaries.md)）
+
+### 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` |
+
+---
+
+## 2. CardGrid（卡片网格）
+
+- **level**: ORGANISM
+- **layer**: business
+- **shadcnImpl**: null（CSS Grid 实现，无独立 UI 组件）
+- **场景**：承载多个 ItemCard，使用 CSS Grid `auto-fill` + `minmax` 自动响应式列数。
+
+### 2.1 props
+
+| prop | 取值 | 说明 |
+|------|------|------|
+| minWidth | 必须引用 `var(--card-grid-min-*)` | 最小列宽（H2 修复，禁止字面量） |
+| gap | `var(--card-gap)` 默认 16px | 卡片间距 |
+| alignContent | literal: `'start'` | 防止卡片拉伸变形 |
+| children | `ItemCard[]` | 仅承载业务卡片 |
+
+### 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;
+}
+```
+
+### 2.3 presets（4 套预设）
+
+| 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`。
+
+### 2.4 responsive（参考列数，由 auto-fill 自动计算，无需手写断点）
+
+| viewport | columns |
+|----------|---------|
+| ≥1400px | 4 |
+| 1080-1400px | 3 |
+| 768-1080px | 2 |
+| <768px | 1 |
+
+### 2.5 constraints（硬约束）
+
+- 禁止手动写 `grid-template-columns` 字面量（必须用 `minmax + var(--min-width)`）
+- 禁止 `alignContent: stretch`（会导致卡片高度被拉伸变形）
+- 禁止在 CardGrid 与 ItemCard 之间插入额外 wrapper
+
+---
+
+## 3. CardActionBar（卡片操作栏）
+
+- **level**: MOLECULAR
+- **layer**: business
+- **shadcnImpl**: null
+- **UI 组件库引用**: 组合使用 `components/button` → `Button` (variant='ghost', size='sm') + `components/dropdown-menu` → `DropdownMenu`（溢出操作）+ `components/separator` → `Separator`（按钮间分隔）
+- **场景**：ItemCard 底部的操作栏 — 滑条式 (SlideBar) 设计，白底 + 主要文字色 + 等分宽度（v7.3.1 从主色底调整为白底以提升可读性与表单化一致性）。
+
+### 3.1 props
+
+| prop | 取值 | 说明 |
+|------|------|------|
+| actions | `Array<{ label, onClick, destructive? }>` | 操作列表 |
+| mode | `'hover-slidebar' \| 'hover-fade' \| 'always-visible'` | 三态，默认由 ItemCard.density 决定，pattern 可覆写 |
+| rows | 1 \| 2 | complex 模式可分行 |
+
+### 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)`），全局调整背景时不需修改本节
+
+### 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)`（保持红色）
+- 位置：始终放在最后
+
+### 3.4 modes 实现表（三态完整 CSS）
+
+##### 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 状态切换可见性
+
+### 3.5 rowsRule（按钮行规则）
+
+**single（rows=1）**：
+- max: 4 个按钮
+- buttonGap: 8px
+- overflow: 操作 >5 个时，剩余进入「更多 ▾」Dropdown
+  - **UI 组件库引用**: `components/dropdown-menu` → `DropdownMenu` + `DropdownMenuTrigger` + `DropdownMenuContent` + `DropdownMenuItem`
+
+**double（rows=2）**：
+- row1: 高频操作（管理/编辑/详情等，≤4 个）
+- row2: 低频操作 + 「更多 ▾」（续费/导出/删除等）
+- buttonGap: 8px
+- rowGap: 4px
+
+### 3.6 actionBehavior（操作触发后的页面流转，引用 page-flow.json crudFlow）
+
+| action | confirm | target | after |
+|--------|---------|--------|-------|
+| 查看/详情 | false | DetailPage | 返回保持筛选 |
+| 编辑 | false | FormPage / Sheet | 保存后返回原页 |
+| 导出 | false | 文件下载 | — |
+| 删除 | Dialog 二次确认（level3）| API 调用 | 刷新列表 |
+
+### 3.7 constraints（硬约束）
+
+- **样式**：禁止使用文字按钮或 Primary Button 替代滑条式样式
+- **背景**：`var(--card)` 白底（v7.3.1），与 ContentCard 保持一致；禁止使用主色底
+- **文字**：`var(--gray-primary)` 主要文字色（v7.3.1）；hover 转 `var(--primary)` 提示可点击
+- **动画**：仅使用本节 §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 浅灰分割线），最后一个按钮无右边框