@teamix-evo/skills 0.4.0 → 0.6.0

package/src/teamix-evo-design-opentrek/checklist.md

@@ -8,19 +8,20 @@
 
 ## 强制项（12）
 
-| #   | 检查点                                                  | 失败示例                                            | 通过条件                                                       | 规则           |
-| --- | ------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------- | -------------- |
-| 1   | 无硬编码色值                                            | `bg-[#fff]` / `style={{color:'red'}}`               | 走语义 token：`bg-background` / `text-foreground`              | [F1]           |
-| 2   | 状态不用原始色                                          | `text-green-500` / `bg-red-100`                     | `<Badge variant="secondary">` / `text-destructive`             | [S8]           |
-| 3   | 间距用 gap                                              | `space-y-4`                                         | `flex flex-col gap-4`                                          | [S2]           |
-| 4   | className 不覆盖组件颜色 / 字体                         | `<Button className="bg-blue-500">`                  | `<Button variant="default">`                                   | [S1]           |
-| 5   | 复合组件结构完整                                        | `<Dialog>` 缺 DialogTitle / `<Tabs>` 直接放 Trigger | Dialog ≥ Title；Card ≥ Header+Content；Tabs 含 List；详见 C 组 | [C1-C12]       |
-| 6   | 状态 / 占位 / 分隔走专用组件                            | 自定义 styled span 当 Badge / animate-pulse div     | Badge / Skeleton / Empty / Separator / Alert / `toast()`       | [C7-C12]       |
-| 7   | 图标用 data-icon，不设尺寸类                            | `<SearchIcon className="size-4 mr-2" />`            | `<SearchIcon data-icon="inline-start" />`                      | [I1-I2]        |
-| 8   | 不手动 z-index / dark: 覆盖                             | `className="z-50"` / `dark:bg-gray-950`             | 删除 z-index（组件自管）；用语义 token                         | [S5] [S7]      |
-| 9   | 条件类名用 cn()                                         | `` `${active ? 'a' : 'b'}` ``                       | `cn('base', active ? 'a' : 'b')`                               | [S6]           |
-| 10  | 危险操作二次确认                                        | `<Button onClick={delete}>删除</Button>`            | `<AlertDialog>` + 陈述句标题 + 影响列表 + 重复动词按钮         | P4 [philosophy] |
-| 11  | 可交互元素显式带手型                                    | `<button onClick={...}>` 不带 `cursor-pointer`      | `cursor-pointer` + `disabled:cursor-not-allowed`               | [ADR0023]      |
+| # | 检查点 | 失败示例 | 通过条件 | 规则 |
+| --- | --- | --- | --- | --- |
+| 1 | 无硬编码色值 | `bg-[#fff]` / `style={{color:'red'}}` | 走语义 token:`bg-background` / `text-foreground` | [F1] |
+| 2 | 状态不用原始色 | `text-green-500` / `bg-red-100` | `<Badge variant="secondary">` / `text-destructive` | [S8] |
+| 3 | 间距用 gap | `space-y-4` | `flex flex-col gap-4` | [S2] |
+| 4 | className 不覆盖组件颜色 / 字体 | `<Button className="bg-blue-500">` | `<Button variant="default">` | [S1] |
+| 4.1 | Button 不传 size | `<Button size="sm">` / `<Button size="sm" className="h-9 w-9 p-0">` | `<Button>...</Button>`(default = `h-8` + `text-xs` 12px,ADR 0027 对齐 cd hybridcloud form-element-medium);icon-only 用 `size="icon"` | [ADR0027] |
+| 5 | 复合组件结构完整 | `<Dialog>` 缺 DialogTitle / `<Tabs>` 直接放 Trigger | Dialog ≥ Title;Card ≥ Header+Content;Tabs 含 List;详见 C 组 | [C1-C12] |
+| 6 | 状态 / 占位 / 分隔走专用组件 | 自定义 styled span 当 Badge / animate-pulse div | Badge / Skeleton / Empty / Separator / Alert / `toast()` | [C7-C12] |
+| 7 | 图标用 data-icon,不设尺寸类 | `<SearchIcon className="size-4 mr-2" />` | `<SearchIcon data-icon="inline-start" />` | [I1-I2] |
+| 8 | 不手动 z-index / dark: 覆盖 | `className="z-50"` / `dark:bg-gray-950` | 删除 z-index(组件自管);用语义 token | [S5] [S7] |
+| 9 | 条件类名用 cn() | `` `${active ? 'a' : 'b'}` `` | `cn('base', active ? 'a' : 'b')` | [S6] |
+| 10 | 危险操作二次确认 | `<Button onClick={delete}>删除</Button>` | `<AlertDialog>` + 陈述句标题 + 影响列表 + 重复动词按钮 | P4 [philosophy] |
+| 11 | 可交互元素显式带手型 | `<button onClick={...}>` 不带 `cursor-pointer` | `cursor-pointer` + `disabled:cursor-not-allowed` | [ADR0023] |
 
 > **强制项 #12(并入 #11 的纪律范围,与 [ADR 0024](../../../../../docs/adr/0024-scoped-css-radix-state-conflict.md) 同步)**:hover / focus 视觉反馈(border / bg / shadow)写在组件源码 className 时**必须**用 `enabled:` 前缀,disabled 态不触发样式变化。失败示例 `hover:border-primary`(disabled 仍响应);通过示例 `enabled:hover:border-primary`。Radix `data-state="checked"` / `"indeterminate"` / `"on"` 激活态视觉由组件自管,uni-manager scoped CSS 已统一在 `:not()` 链里排除这三个态值,新组件接入 `border-input` 类时务必核对。
 >
@@ -28,6 +29,7 @@
 
 [F1]: ./boundaries.md
 [ADR0023]: ../../../../../docs/adr/0023-cursor-pointer-explicit-in-component-source.md
+[ADR0027]: ../../../../../docs/adr/0027-component-visual-token-alignment.md
 [S1]: ./boundaries.md
 [S2]: ./boundaries.md
 [S5]: ./boundaries.md

package/src/teamix-evo-design-opentrek/components.md

@@ -1,5 +1,8 @@
 # Components — 选型决策与组合规则
 
+> ⚠️ **Prerequisites**: 你必须已完成 [generation-flow.md](./generation-flow.md) Step 1–3（已确定页面类型 + 子类型 + 区域骨架）后才能读本文件。
+> 若未完成前置步骤，请先返回 [generation-flow.md](./generation-flow.md) 从 Step 1 开始。
+
 > **本文档只回答"用什么组件、怎么搭配"，不写具体 Props / Examples / import 路径。**
 > 组件 API、Props、示例代码通过 MCP `get_component_meta` 实时查询；可用列表通过 `list_components` / `find_components` 查询。
 
@@ -13,24 +16,29 @@
 
 调用 `list_components` / `find_components` 命中失败、或本文件提到的组件名（例如 `SearchCombo` / `ContextSwitcher` / `ItemCard` / `CardGrid` / `CardActionBar`）在 `@teamix-evo/biz-ui` 中无实物时。
 
-### 0.2 三步处置法
+### 0.2 四步处置法
 
 1. **不要自造同名组件入 `src/components/`** — 即使本文件提到该组件名，也必须先确认实物存在。
-2. **改用 `@teamix-evo/ui` 中语义近似的原子组件做最小拼装**（参见本文件 §3 决策树和 §5 拼凑配方）。
-3. **在响应中显式声明替代关系**，例如：
+2. **优先扫所有 ui 单体找语义等价**（见 §0.4） — 在 `@teamix-evo/ui` 约 89 个原子件中用 `find_components` 模糊搜 + 按七类法分类筛，找功能 / 结构等价的**单体**直接用。**这一步不可跳**。
+3. **单体彻底无等价 → 才用 ui 多原子最小拼装**（参见本文件 §3 决策树和 §5 拼凑配方）。
+4. **在响应中显式声明替代关系**，例如：
 
-   > `// SearchCombo 暂未实物化 → 用 Input + Select + Button 拼装`
+   > `// SearchCombo 暂未实物化 → ui filter-bar 单体语义等价 → 直接采用` > `// 或：// SearchCombo 暂未实物化 → 89 件单体扫尽无等价 → Input + Select + Button 最小拼装`
 
 ### 0.3 兜底优先序
 
 ```text
-biz-ui 实物组件 (优先)
+biz-ui 实物组件（优先）
+  ↓ 未命中
+ui 原子 — 精确名匹配（dialog→Dialog / button→Button…）
   ↓ 未命中
-ui 原子组件最小拼装 (兜底)
+ui 原子 — 语义近似单体替代（扫所有 89 件，见 §0.4）  ← 关键档：穷尽前不允许进下一档
+  ↓ 仍未命中
+ui 多原子最小拼装（万不得已，注释声明）
   ↓ 仍无法表达
 跳转 patterns/*.md 找页面级模板
   ↓ 仍无法表达
-回报用户：缺组件 + 已尝试拼装方案
+回报用户：缺组件 + 已尝试单体扫描记录 + 拼装方案
 ```
 
 **永远不要**：
@@ -38,22 +46,60 @@ ui 原子组件最小拼装 (兜底)
 - 在 `src/components/` 下新增与 biz-ui 同名的"私有版本"
 - 用 antd / arco / chakra 等其它库填补缺口
 - 在 skill 响应中写"假设 biz-ui 有 X"而不实查 MCP
+- **跳过 §0.4 直接进多原子拼装** — 属于"以拼代查"，违反单体优先原则
+
+---
+
+### 0.4 语义近似单体扫描指南（兜底关键步骤）
+
+> 「**语义近似单体**」= ui 89 个原子里找到一个**功能等价 / 结构相容 / 视觉中性**的组件直接使用，避免几个原子捆一起的拼装代价。这是 §0.3 第 3 档的实操定义。
+
+**扫描三板斧**：
+
+1. **关键词模糊搜**：`find_components(kw)` 多关键词试 — 例 `SearchBox` → 试 `search` / `find` / `query` / `filter` / `combo`
+2. **七类法分类筛**（按要做的事归类，再翻该类下的 ui 原子）：
+   - `general`：Button / Icon / Typography
+   - `layout`：Flex / Grid / Space / Separator / Sidebar / PageHeader / Card / Container
+   - `navigation`：Breadcrumb / Pagination / DropdownMenu / Steps / NavigationMenu / Tabs
+   - `data-entry`：参见 §3.6 输入控件
+   - `data-display`：参见 §3.4 / §3.5；含 Accordion / Tooltip / Table / DataTable / Badge / Tag / Avatar / Descriptions / Statistic
+   - `feedback`：Alert / Dialog / Sheet（抽屉） / Popover / Progress / Spinner / Empty / Skeleton / Sonner
+   - `deprecated`：不出现在 `list_components` 默认结果，无视
+3. **能力边界核对**：候选单体用 `get_component_meta(name)` 确认 Props 是否承载所需语义，避免"看名字像"实际不通
+
+**典型语义近似映射**（仅示例，使用前仍需 MCP 实查）：
+
+| 找不到的概念       | 优先尝试单体（语义近似）                        | 万不得已的拼装兜底                |
+| ------------------ | ----------------------------------------------- | --------------------------------- |
+| `ItemCard`         | `card`（直接用）                                | CardHeader + CardContent + Footer |
+| `SearchCombo`      | `filter-bar`（直接用）                          | Input + Select + Button           |
+| `ContextSwitcher`  | `dropdown-menu` / `command` + `popover`（拼装） | command + popover + avatar        |
+| `Empty` / `NoData` | `empty`（直接用）                               | div + Icon + Text                 |
+| `Loading`          | `spinner` / `skeleton`（直接用）                | div + animate-spin                |
+| `ConfirmDialog`    | `alert-dialog`（直接用）                        | dialog + button + text            |
+| `StatusTag`        | `badge` / `tag`（按 §3.3）                      | div + dot + text                  |
+
+**严禁反模式**：
+
+- 单体语义等价时仍按概念名拼装（例：明明有 `empty` 偏写 `<div className="flex flex-col items-center"><Icon><span>暂无数据</span></div>`）
+- 把"最小拼装"理解为"多原子捆绑就行"，而不是先**穷尽 88 件单体**
 
 ---
 
 ## 1. 双层组件架构（实物归属）
 
-| 层级                                       | 来源                          | 实物清单（截至当前 variant）                                                                                                                                                                                                                                    |
-| ------------------------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **业务扩展层（biz-ui，opentrek variant）** | `@teamix-evo/biz-ui/opentrek` | 仅 2 个实物：`list-card`、`op-sidebar`。其余 `business/` 目录为文档草稿，**不可 import**。                                                                                                                                                                      |
-| **ui 实现层（shadcn 原子）**               | `@teamix-evo/ui`              | ≈ 89 个原子/复合组件。包含 **PageHeader / Pagination / Steps / Tabs / Tooltip / DataTable / FilterBar / Combobox(=command) / AutoComplete / DatePicker / Drawer / Sheet / Dialog / AlertDialog / Card / Badge / Tag / Alert / Toast(sonner) / Form** 等高频件。 |
+| 层级                                       | 来源                          | 实物清单（截至当前 variant）                                                                                                                                                                                                     |
+| ------------------------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **业务扩展层（biz-ui，opentrek variant）** | `@teamix-evo/biz-ui/opentrek` | 3 个实物：`list-card`、`op-sidebar`、`op-page-container`。其余 `business/` 目录为文档草稿，**不可 import**。                                                                                                                     |
+| **ui 实现层（shadcn 原子）**               | `@teamix-evo/ui`              | ≈ 76 个原子/复合组件。包含 **PageHeader / Pagination / Steps / Tabs / Tooltip / DataTable / FilterBar / Command / Combobox / DatePicker / Sheet / Dialog / AlertDialog / Card / Badge / Tag / Alert / Sonner / Form** 等高频件。 |
 
 ### 1.1 选型铁律
 
-1. **优先 biz-ui 实物层** — 已封装变体 + 文案规范，但**注意 opentrek 当前仅 2 个实物**。
-2. **biz-ui 无实物 → ui 实现层** — 89 个原子件覆盖绝大部分场景。
-3. **ui 仍无 → §5 拼凑配方** — 用 ui 多个原子件最小组合（不私造）。
-4. **禁止**自造同名组件（违反 reuse-first，详见 §0）。
+1. **优先 biz-ui 实物层** — 已封装变体 + 文案规范，但**注意 opentrek 当前仅 3 个实物**。
+2. **biz-ui 无实物 → ui 单体精确名匹配** — 按组件名 / 显式语义直查 `find_components`。
+3. **精确名未命中 → ui 单体语义近似扫描**（见 §0.4） — 在 88 件里找等价单体直接用，**这一步不可跳**。
+4. **单体彻底无等价 → §5 多原子最小拼装** — 仅作为单体穷尽后的兜底。
+5. **禁止**自造同名组件（违反 reuse-first，详见 §0）。
 
 ### 1.2 实时校验
 
@@ -75,7 +121,7 @@ ui 原子组件最小拼装 (兜底)
 
 ## 3. 选型决策树
 
-### 3.1 反馈与确认 — Dialog vs Sheet vs Drawer vs Popover
+### 3.1 反馈与确认 — Dialog vs Sheet vs Popover
 
 ```text
 需要用户做出决定 / 阻塞主流程？
@@ -84,7 +130,7 @@ ui 原子组件最小拼装 (兜底)
 │   └─ 复杂表单（< 8 字段）→ Dialog
 └─ 否
     ├─ 临时编辑/筛选（侧边滑出）→ Sheet
-    ├─ 多级下探查看（侧边可叠层）→ Drawer
+    ├─ 多级下探查看（侧边可叠层）→ Sheet（多层叠加模式）
     ├─ 内容预览/上下文操作（小气泡）→ Popover
     └─ 仅展示信息（鼠标悬浮）→ Tooltip
 ```
@@ -100,17 +146,17 @@ ui 原子组件最小拼装 (兜底)
 
 > 来源：Teamix-UI 容器规范。
 
-| 类别       | 容器                                            | 何时使用                                         |
-| ---------- | ----------------------------------------------- | ------------------------------------------------ |
-| **操作型** | 全页面（FormPage）                              | 字段多 / 步骤多 / 需要持久 URL                   |
-| **操作型** | 弹窗模态（Dialog）                              | 阻塞主流程的简短确认或表单；最多 2 级，不再深入  |
-| **操作型** | 气泡（Popconfirm）                              | 二次确认（删除/解绑），轻量提示                  |
-| **展示型** | 全页面（DetailPage）                            | 完整信息查看，路由可分享                         |
-| **展示型** | 抽屉非模态（Sheet）                             | 不阻塞主流程，可保留上下文（如侧栏 Detail）      |
-| **展示型** | 抽屉模态（Drawer）                              | 多级下探查看（如资源 → 子资源 → 配置），逐层推出 |
-| **展示型** | 弹窗模态（Dialog）                              | 一次性展示重要信息                               |
-| **展示型** | 卡片（Card）                                    | 同级信息分组；卡片之间间距 16px                  |
-| **展示型** | 通知反馈（Toast/Sonner / Alert / Notification） | 瞬时反馈 / 页面级横幅 / 系统通知                 |
+| 类别       | 容器                       | 何时使用                                         |
+| ---------- | -------------------------- | ------------------------------------------------ |
+| **操作型** | 全页面（FormPage）         | 字段多 / 步骤多 / 需要持久 URL                   |
+| **操作型** | 弹窗模态（Dialog）         | 阻塞主流程的简短确认或表单；最多 2 级，不再深入  |
+| **操作型** | 气泡（Popconfirm）         | 二次确认（删除/解绑），轻量提示                  |
+| **展示型** | 全页面（DetailPage）       | 完整信息查看，路由可分享                         |
+| **展示型** | 抽屉非模态（Sheet）        | 不阻塞主流程，可保留上下文（如侧栏 Detail）      |
+| **展示型** | 抽屉模态（Sheet 多层叠加） | 多级下探查看（如资源 → 子资源 → 配置），逐层推出 |
+| **展示型** | 弹窗模态（Dialog）         | 一次性展示重要信息                               |
+| **展示型** | 卡片（Card）               | 同级信息分组；卡片之间间距 16px                  |
+| **展示型** | 通知反馈（Sonner / Alert） | 瞬时反馈 / 页面级横幅 / 系统通知                 |
 
 ### 3.3 状态展示 — Badge vs Tag vs Alert
 
@@ -149,12 +195,14 @@ ui 原子组件最小拼装 (兜底)
 ```text
 枚举值 ≤ 7 → RadioGroup（一屏可见）
 枚举值 8~30 → Select
-枚举值 > 30 / 需搜索 → Combobox（= ui command）
-多选 → MultiSelect / Checkbox
+枚举值 > 30 / 需搜索 → Combobox（输入即建议，支持 multiple 多选）或 Command + Popover 拼装
+多选 → Combobox (multiple={true}) / Checkbox
+数值（整数/小数/金额）→ InputNumber（带 min/max/step/precision）
+数值范围可视化 → Slider（仅用于资源配比/阈值的拖拽式选择）
 日期 → DatePicker / DateRangePicker
-富文本 → Textarea / RichEditor
+富文本 → Textarea
 文件 → Upload
-自动补全 → AutoComplete
+自动补全 → Combobox
 ```
 
 ---
@@ -176,15 +224,16 @@ ui 原子组件最小拼装 (兜底)
 
 ## 5. 业务扩展层（候补）— 实物 vs 概念 + 拼凑配方
 
-> opentrek variant 当前**只有 2 个**实物业务组件：`list-card`、`op-sidebar`。
+> opentrek variant 当前有 **3 个**实物业务组件：`list-card`、`op-sidebar`、`op-page-container`。
 > 以下表格区分"已实物化"与"概念占位（用 ui 拼装）"。
 
 ### 5.1 已实物化（直接使用）
 
-| 组件           | 用途                              | 归属            |
-| -------------- | --------------------------------- | --------------- |
-| **list-card**  | 列表页卡片化展示（替代 ItemCard） | biz-ui/opentrek |
-| **op-sidebar** | 主导航侧栏                        | biz-ui/opentrek |
+| 组件                  | 用途                                      | 归属            |
+| --------------------- | ----------------------------------------- | --------------- |
+| **list-card**         | 列表页卡片化展示（替代 ItemCard）         | biz-ui/opentrek |
+| **op-sidebar**        | 主导航侧栏                                | biz-ui/opentrek |
+| **op-page-container** | 页面容器（白卡 + 间距 + PageHeader 插槽） | biz-ui/opentrek |
 
 ### 5.2 概念占位（按配方拼装）
 
@@ -237,8 +286,9 @@ ui 原子组件最小拼装 (兜底)
 通用结构性规则 → 见 [checklist.md](./checklist.md)（C1-C12 / I1-I4）。本文件特有的"选型决策"自检：
 
 - [ ] 已先用 `find_components` 验证组件存在性（不靠默认）
-- [ ] biz-ui 命中失败 → 改用 ui 原子件，按 §5.2 配方拼装并加注释
-- [ ] 反馈 / 确认场景按容量选 Dialog / Sheet / Drawer / Popover
+- [ ] biz-ui 命中失败 → **先按 §0.4 扫所有 ui 单体找语义近似替代**，单体覆盖时直接采用，未直接跳到 §5 拼装
+- [ ] 单体彻底无等价时 → §5 拼装代码必加注释 `// 已扫尽 89 件 ui 单体无语义等价 → 拼装`
+- [ ] 反馈 / 确认场景按容量选 Dialog / Sheet / Popover
 - [ ] 容器层级 ≤ 3，弹窗最多 2 级，超过则跳转全页面
 - [ ] 卡片列表优先 biz-ui `list-card`，否则用 `card[] + grid` 拼
 - [ ] 表格 ≤ 6 列，超过改 DataTable + 列控制