@teamix-evo/skills 0.3.0 → 0.5.0

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

@@ -0,0 +1,274 @@
+# Foundations — Token 用法指南
+
+> ⚠️ **何时读本文件**: [generation-flow.md](./generation-flow.md) Step 6（视觉填充）强制要求完整读取。
+> 任何色彩、间距、字号、圆角、阴影、动效必须基于本文件的 Token 定义，不得凭记忆生成。
+
+> **核心原则**：所有视觉值必须来自 `@teamix-evo/tokens` 暴露的 CSS 变量；禁止硬编码颜色、间距、圆角、阴影、时长。
+
+---
+
+## 0. AI 实操路径(读本文档前先做)
+
+**本文档解释"如何用 token",但 token 的真实集合在 MCP 工具里**。写组件样式前必须按这个顺序:
+
+1. **调 `tokens_list()`** — 拿到当前 variant 下所有 token 的扁平列表(category / name / values / description)。这是判断"有哪些语义槽位可用"的唯一权威来源,markdown 文档随时可能落后于 `base.tokens.json`。
+2. **或调 `tokens_search({ query })`** — 已知关键词(如 "primary" / "destructive" / "card-gap")时更便宜。
+3. **可选调 `tokens_get()`** — 需要原文 CSS(`tokens.theme.css` / `tokens.overrides.css`)拿去 copy-paste 时再调。
+4. **回到本文档** — 查"如何用"(命名约定、铁律、字号阶梯、组件 token 槽位等本文 §1-N 内容)。
+
+> **不要跳过 MCP 直接读本文档**:本文档列的是稳定的**用法**,不是实时的**清单**。如果只读 markdown,会错过 variant 切换、tokens.overrides.css 自定义、新增 `chart-*` / `sidebar-*` 等 token —— 这些都只有 MCP 才能给出当下真实状态。
+
+---
+
+## 1. Token 体系总览
+
+| 层级          | 来源                                | 用途                                                    |
+| ------------- | ----------------------------------- | ------------------------------------------------------- |
+| **Primitive** | `tokens/theme.css` 私有变量         | 原子值（不直接消费）                                    |
+| **Semantic**  | `--color-bg-*`、`--color-text-*` 等 | AI/开发者唯一可用层                                     |
+| **Component** | `tailwind.config` 映射              | 通过 `bg-background`、`text-foreground` 等 utility 消费 |
+
+**铁律**：
+
+- ✅ `bg-background` `text-foreground` `border-border`（语义类）
+- ❌ `bg-[#fff]` `text-gray-500` `border-[1px_solid_#ddd]`（硬编码）
+
+---
+
+## 2. 排版 Typography
+
+### 2.1 字号阶梯（9 档）
+
+| Token       | rem   | 用途                         |
+| ----------- | ----- | ---------------------------- |
+| `text-xs`   | 0.75  | 辅助说明、表格次级文本       |
+| `text-sm`   | 0.875 | 表单标签、按钮文本、表格正文 |
+| `text-base` | 1.0   | 正文默认                     |
+| `text-lg`   | 1.125 | 卡片标题、对话框内标题       |
+| `text-xl`   | 1.25  | 区块标题                     |
+| `text-2xl`  | 1.5   | 页面 H2                      |
+| `text-3xl`  | 1.875 | 页面 H1                      |
+| `text-4xl`  | 2.25  | 营销/Dashboard 数字大屏      |
+| `text-5xl`  | 3.0   | Hero / 数据看板核心指标      |
+
+### 2.2 字重（4 档）
+
+- `font-normal` (400) — 正文
+- `font-medium` (500) — 强调、按钮、表头
+- `font-semibold` (600) — 区块标题
+- `font-bold` (700) — 页面主标题、Hero
+
+### 2.3 行高与字距
+
+- 正文 `leading-normal` (1.5)；标题 `leading-tight` (1.25)；超长文段 `leading-relaxed` (1.625)
+- 默认字距走 token，**不手动调 `tracking-*`**（除非 ≥ `text-3xl` 的标题可加 `tracking-tight`）
+
+### 2.4 排版规则
+
+- 一个页面层级 ≤ 3 级（H1 + H2 + 正文）
+- 同一区块内不混用 4 种以上字号
+- **禁止** 用 `text-[14px]` 这类任意值
+
+---
+
+## 3. 间距 Spacing（4px 网格）
+
+### 3.1 基础尺度
+
+所有间距走 `0`、`1`(4px)、`2`(8px)、`3`(12px)、`4`(16px)、`6`(24px)、`8`(32px)、`12`(48px)、`16`(64px) 整数档；**禁止** `5`/`7`/`9`/`11` 等奇数档与 `gap-[10px]` 任意值。
+
+### 3.2 决策指南
+
+| 关系                  | 间距               | 示例          |
+| --------------------- | ------------------ | ------------- |
+| 紧密相关（图标+文字） | `gap-1` / `gap-2`  | Badge 内图标  |
+| 同组元素（表单字段）  | `gap-3` / `gap-4`  | FormItem 之间 |
+| 区块内段落            | `gap-4` / `gap-6`  | Card 内多段   |
+| 区块之间              | `gap-6` / `gap-8`  | Section 之间  |
+| 页面主区块            | `gap-8` / `gap-12` | 页面级布局    |
+
+### 3.3 容器内边距
+
+- Dialog / Sheet body：`p-6`
+- Card body：`p-4` 或 `p-6`（看密度）
+- Page Container：`px-6 py-4`（移动端 `px-4`）
+- Toolbar：`px-4 py-2`
+
+### 3.4 间距规则
+
+- **多元素间距用 `gap-*`，不用 `space-x-*`/`space-y-*`**（参见 boundaries.md S2）
+- 同一容器内 padding 与 child gap 不要同时出现两种节奏
+
+### 3.5 表单专用三档间距（通用规范，反哺自 Teamix-UI 规范文档）
+
+表单内部固定使用三档间距，禁止其他取值；适用于所有 Form / FormItem / FieldGroup 布局：
+
+| 档位     | 间距 | Tailwind | 适用                          |
+| -------- | ---- | -------- | ----------------------------- |
+| Tight    | 4px  | `gap-1`  | Label ↔ 字段；字段 ↔ 帮助文本 |
+| Standard | 20px | `gap-5`  | 同分组内多个 FormItem 之间    |
+| Section  | 32px | `gap-8`  | 表单分段（FormSection）之间   |
+
+> 例外：Drawer 内嵌简表单（≤ 5 字段）可整体收紧到 Tight + 16px section。**不要**自创 24px / 28px 等中间档。
+
+### 3.6 Input 宽度五档（通用规范，反哺自 Teamix-UI 规范文档）
+
+所有 Input / Select / DatePicker 等输入控件**必须**使用以下五档宽度之一，禁止任意 px / 百分比：
+
+| 档位 | 宽度 | 适用场景                                     |
+| ---- | ---- | -------------------------------------------- |
+| XS   | 104  | 数字、状态、单位（端口号 / 数量 / 状态选择） |
+| S    | 216  | 短文本、单选（实例名片段、短标识）           |
+| M    | 328  | **默认**。常规字段（名称、邮箱、电话）       |
+| L    | 440  | 长文本、URL、嵌套路径                        |
+| XL   | 552  | 描述、备注、长 URL；超过则换 Textarea        |
+
+实现:
+
+```tsx
+// 通过 CSS 变量统一消费，便于变体覆盖
+<Input style={{ width: 'var(--field-input-m)' }} />
+```
+
+> tokens 包将 `--field-input-xs/s/m/l/xl` 暴露为 CSS 变量；具体数值由变体（opentrek / uni-manager）覆盖，但**档位语义统一**。
+
+---
+
+## 4. 色彩语义 Color Semantic
+
+### 4.1 五大语义类别
+
+| 类别         | Token 前缀                                                             | 用途               |
+| ------------ | ---------------------------------------------------------------------- | ------------------ |
+| **Surface**  | `bg-background` `bg-card` `bg-muted` `bg-popover`                      | 容器底色           |
+| **Text**     | `text-foreground` `text-muted-foreground`                              | 正文与次要文字     |
+| **Action**   | `bg-primary` `text-primary-foreground` `bg-secondary` `bg-destructive` | 可交互元素         |
+| **Boundary** | `border-border` `border-input` `ring-ring`                             | 边框、分隔、聚焦环 |
+| **Feedback** | `bg-destructive` `bg-warning` `bg-success` `bg-info`                   | 状态反馈           |
+
+### 4.2 状态色映射（仅用于 Badge / Alert / Toast）
+
+| 状态 | 类名组合                             |
+| ---- | ------------------------------------ |
+| 成功 | `bg-success/10 text-success`         |
+| 警告 | `bg-warning/10 text-warning`         |
+| 错误 | `bg-destructive/10 text-destructive` |
+| 信息 | `bg-info/10 text-info`               |
+| 中性 | `bg-muted text-muted-foreground`     |
+
+### 4.3 色彩规则
+
+- **禁止** 用原始色（`bg-red-500`、`text-blue-600`）表达状态（参见 boundaries.md S8）
+- **禁止** 自定义 `dark:` 覆盖 — 暗色模式由 token 自动切换
+- 透明度走 `/10` `/20` `/50` 这类 token 比例，不写 `rgba()`
+
+---
+
+## 5. 圆角 Radius
+
+### 5.1 七档梯度
+
+| Class          | 用途                     |
+| -------------- | ------------------------ |
+| `rounded-none` | 表头、对齐网格、表格     |
+| `rounded-sm`   | 小型 Tag、Badge          |
+| `rounded`      | 输入框、按钮（默认）     |
+| `rounded-md`   | Card 默认                |
+| `rounded-lg`   | Dialog、Popover、Sheet   |
+| `rounded-xl`   | Hero 卡片、营销组件      |
+| `rounded-full` | Avatar、圆形按钮、状态点 |
+
+### 5.2 组件速查
+
+- **Button** → `rounded-md`（default）/ `rounded-full`（icon-only）
+- **Input / Select / Textarea** → `rounded-md`
+- **Card** → `rounded-lg`
+- **Dialog / Sheet** → `rounded-lg`
+- **Avatar** → `rounded-full`
+- **Badge** → `rounded-md`（信息型）/ `rounded-full`（状态型）
+
+### 5.3 规则
+
+- 同一视觉层级保持一致圆角（一个区块内不混用）
+- **禁止** `rounded-[6px]` 任意值
+
+---
+
+## 6. 阴影 Shadow
+
+### 6.1 六级阴影
+
+| Class         | 层级语义                      | z-index 对应 |
+| ------------- | ----------------------------- | ------------ |
+| `shadow-none` | 平铺、内联、表格              | base         |
+| `shadow-sm`   | Card 静态                     | 10           |
+| `shadow`      | Hover 提升、Dropdown          | 20           |
+| `shadow-md`   | Popover、Tooltip              | 30           |
+| `shadow-lg`   | Sheet、Drawer                 | 40           |
+| `shadow-xl`   | Dialog、Modal、CommandPalette | 50           |
+
+### 6.2 规则
+
+- **禁止** 直接写 `z-[9999]`、`z-50` 等任意 z-index（参见 [boundaries.md S5](./boundaries.md)）— z-index 由组件库统一管理
+- 阴影只用于表达"高度层级"，不作装饰
+- 同时升起的元素阴影应一致（如 hover 状态全用 `shadow`）
+
+### 6.3 圆角 × 阴影对应表
+
+> 圆角与阴影**必须同档对应**:低层级元素(列表项)即使 hover 也不应跳到 `shadow-lg`。
+
+| 元素            | 圆角           | 阴影                      |
+| --------------- | -------------- | ------------------------- |
+| 按钮 / 输入框   | `rounded-md`   | `shadow-sm`               |
+| 卡片            | `rounded-lg`   | `shadow-sm` ~ `shadow-md` |
+| Popover / Toast | `rounded-md`   | `shadow-md`               |
+| Dialog / Sheet  | `rounded-lg`   | `shadow-xl`               |
+| 头像 / 药丸标签 | `rounded-full` | `shadow-none`             |
+
+---
+
+## 7. 动效 Motion
+
+### 7.1 时长四档
+
+| Token          | ms  | 用途                              |
+| -------------- | --- | --------------------------------- |
+| `duration-75`  | 75  | 微反馈（按钮按下、勾选）          |
+| `duration-150` | 150 | 默认过渡（hover、focus）          |
+| `duration-200` | 200 | 入场（Tooltip、Popover）          |
+| `duration-300` | 300 | 大型容器（Dialog、Sheet、Drawer） |
+
+### 7.2 缓动
+
+- 默认 `ease-out`（大多数入场）
+- 退场 `ease-in`
+- 复杂连续动效 `ease-in-out`
+- **禁止** 自定义 `cubic-bezier()` 任意值
+
+### 7.3 入场 / 退场标准模式
+
+| 场景                | 动画                                                |
+| ------------------- | --------------------------------------------------- |
+| Dialog / Sheet 入场 | `data-[state=open]:animate-in fade-in-0 zoom-in-95` |
+| Sheet 抽屉入场      | `data-[state=open]:slide-in-from-right`             |
+| Tooltip / Popover   | `data-[state=open]:fade-in-0 zoom-in-95`            |
+| Toast               | `slide-in-from-top-full`                            |
+
+### 7.4 动效分级
+
+- **L1 必备**：状态切换（hover / focus / active）— 全站统一 `duration-150`
+- **L2 推荐**：内容入场（列表项渐入、Skeleton 替换）— `duration-200`
+- **L3 增强**：场景转场（页面切换、Drawer 抽屉）— `duration-300`，可酌情增减
+
+### 7.5 规则
+
+- **禁用** `prefers-reduced-motion: reduce` 下的所有 L2/L3 动效（组件库已内置）
+- 动效用于**辅助理解状态变化**，不作装饰；持续 > 400ms 视为故障
+- 不在主流程关键路径加阻塞动画
+
+---
+
+## 8. 自检
+
+→ 见 [checklist.md](./checklist.md) 强制项 1 / 3 / 8 与建议项。  
+本文件只定义 token 的"形式"；"是否使用"由 checklist 与 [boundaries.md](./boundaries.md) F1-F7 / S2 / S5 强制。

package/src/teamix-evo-design-opentrek/generation-flow.md

@@ -0,0 +1,243 @@
+# 生成 / 翻新 / 验证流程
+
+> ⚠️ **本文件是页面级任务的唯一执行路径。每一步都有 GATE 门禁和 MUST READ 文件清单。** > **跳步 = 产出不合规。AI 不得凭"已有知识"省略任何文件读取。**
+
+---
+
+## 1. 生成路径（六步门控）
+
+适用关键词：**"生成 / 创建 / 新建 / 设计一个 / 做一个"**。
+
+```
+Step 1 需求确认 → Step 2 类型识别 → Step 3 子类型 + 布局
+                                            ↓
+Step 7 自检    ← Step 6 视觉填充  ← Step 5 可用性校验 ← Step 4 组件挑选
+```
+
+### Step 1 · 最小 quorum + 默认值
+
+📖 **MUST READ**: [philosophy.md](./philosophy.md)（理解"为什么这么做" — 四大原则优先级）+ [brand.md](./brand.md)（视觉调性 + 文案语气基调）
+
+**只有两个信息缺一不可**（最小 quorum，缺则反问）：
+
+- [ ] **页面类型**：ListPage / DetailPage / FormPage / Dashboard / Dialog（缺则按 Step 2 决策树推断）
+- [ ] **资源实体**：要操作的对象是什么（订单 / 实例 / 用户 / ……）
+
+**其他信息全部走默认值，先生成再细化**（避免连环反问让用户失去耐心）：
+
+| 维度     | 默认                                                | 何时升级                             |
+| -------- | --------------------------------------------------- | ------------------------------------ |
+| 业务领域 | 资源管理                                            | 用户明确说"工作流 / 报表"等          |
+| 用户角色 | 业务管理员                                          | 涉及审计 / 审批 / 平台运维等敏感角色 |
+| 核心动作 | CRUD（增 / 删 / 改 / 查 + 列表）                    | 明确出现"批量 / 审批 / 导出"等关键词 |
+| 入口路径 | 从同名菜单进入，无外部跳转                          | 明确说"从 X 跳到 Y"                  |
+| 子类型   | ListPage→standard / FormPage→single-page / 其余各 1 | 用户提到 wizard / drawer / tabbed 等 |
+
+**反问触发条件**（只有以下情况反问，否则直接出方案）：
+
+1. 页面类型与资源实体均无法从需求中推断
+2. 用户描述与默认值明显冲突（如"我要做一个数据看板"但又说"列表"）
+
+**输出**：页面类型 + 资源实体 + 一句话场景假设（"假设是业务管理员的订单 CRUD 列表，如有偏差请指正"）。
+
+### Step 2 · 页面类型识别
+
+🚧 **GATE**: Step 1 必须已产出"页面类型 + 资源实体 + 场景假设"
+
+📖 **MUST READ**: [patterns/page-types.md](./patterns/page-types.md) §决策树 + §Zone Map
+
+根据 [patterns/page-types.md](./patterns/page-types.md) §决策树匹配类型：
+
+```
+页面内容是什么？
+├─ 多条结构化数据 → ListPage
+├─ 单个记录详情 → DetailPage
+├─ 用户输入数据 → FormPage
+├─ 数据可视化/统计 → Dashboard
+└─ 二次确认 / 快速操作 → Dialog/Sheet
+```
+
+**输出**：页面类型 ID（`ListPage` / `DetailPage` / ...）。
+
+### Step 3 · 子类型识别 + 布局选择
+
+🚧 **GATE**: Step 2 必须已产出"页面类型 ID"
+
+📖 **MUST READ**: 对应的 `patterns/{type}-page.md` + [flows.md](./flows.md)（涉及用户旅程时）
+
+根据页面类型读取对应 `patterns/{type}-page.md`：
+
+- 列表页 6 种子类型：`standard / pure-card / standard-card / drawer / expandable / l2-sidebar / advanced-filter`
+- 详情页 2 种子类型：`tabbed / single-section`
+- 表单页 3 种子类型：`single-page / wizard / drawer-form`
+
+**输出**：子类型 ID + 区域骨架（参照 [patterns/page-types.md](./patterns/page-types.md) §Zone Map）。
+
+### Step 4 · 组件挑选
+
+🚧 **GATE**: Step 3 必须已产出"子类型 ID + 区域骨架"
+
+📖 **MUST READ**: [components.md](./components.md) §0 兗底铁律 + §1 双层架构 + §3 决策树 + §5 拼装配方
+
+读 [components.md](./components.md) §选型决策树确定组件集：
+
+1. 优先使用 `@teamix-evo/ui` 注册表中的稳定组件
+2. 通过 MCP `list_components(status: "stable")` 查可用列表
+3. 通过 MCP `get_component_meta(id)` 查具体 Props/Examples
+4. 复合场景按 [components.md](./components.md) §组合规则装配
+
+**输出**：组件清单 + 每个组件的关键 Props。
+
+### Step 5 · 组件可用性校验（新增 gate）
+
+🚧 **GATE**: Step 4 必须已产出"组件清单 + 每个组件的关键 Props"
+
+> ❗ **此步是 Step 4 → Step 6 的强制闸门**。跳过会导致生成代码引用未安装组件而报错。
+
+对 Step 4 选定的每个组件，执行以下校验：
+
+```text
+① MCP find_components(id) 查询注册表
+   ├─ 命中 entries(活跃) → ②
+   ├─ 命中 deprecatedEntries 且有 replacedBy → 自动替换为 replacedBy 组件，回到 ①
+   ├─ 命中 deprecatedEntries 且无 replacedBy → 走 components.md §0 兔底铁律
+   └─ 未命中 → 走 components.md §0 兔底铁律（原子件拼装）
+
+② 检查目标项目是否已装机
+   ├─ 已装（grep src/components/ui/<id> 或查 manifest.lock.json）→ ✅ 继续
+   └─ 未装 → 输出安装指令：
+       「teamix-evo ui add <id>」
+       等待装机完成后再进入 Step 6
+```
+
+**输出**：校验后的最终组件清单（含替换记录）+ 待安装组件列表（若有）。
+
+### Step 6 · 视觉填充（Token 绑定）
+
+🚧 **GATE**: Step 5 必须已产出"校验后的最终组件清单"
+
+📖 **MUST READ**: [foundations.md](./foundations.md) 全文 + [brand.md](./brand.md) §1 视觉五维（圆角/配色/密度/阴影/焦点风格对齐）+ [patterns/color-mapping.md](./patterns/color-mapping.md)（语义色映射表）
+
+读 [foundations.md](./foundations.md)，所有色彩、间距、字号、圆角、阴影、动效**必须**使用 Token：
+
+| 维度 | Token 入口                                                                   |
+| ---- | ---------------------------------------------------------------------------- |
+| 色彩 | `bg-primary` / `text-foreground` / `border-border` / `text-muted-foreground` |
+| 间距 | Tailwind 4px 网格刻度（`gap-2`/`gap-4`/`p-6` 等）                            |
+| 字号 | `text-xs` / `text-sm` / `text-base` / `text-lg`                              |
+| 圆角 | `rounded-md` / `rounded-lg` / `rounded-full`                                 |
+| 阴影 | `shadow-sm` / `shadow-md` / `shadow-lg`                                      |
+| 动效 | `duration-150` / `duration-300` / `transition-colors`                        |
+
+**禁止**：硬编码 hex 色值、`#xxx` rgb()、内联 `style={{ ... }}`、`text-emerald-600` 等原始色。
+
+**输出**：含 Token 引用的可执行代码 / HTML。
+
+### Step 7 · 自检
+
+🚧 **GATE**: Step 6 必须已产出"含 Token 引用的可执行代码"
+
+📖 **MUST READ**: [boundaries.md](./boundaries.md) 全文（38 条硬规则）+ [checklist.md](./checklist.md) 全文
+
+对照 [checklist.md](./checklist.md) 10 项逐项验证：
+
+- 通过 → 输出最终代码
+- 不通过 → 回到对应失败项的步骤修正后重新自检
+
+**输出**：合规代码 + 自检报告。
+
+---
+
+## 2. 翻新路径
+
+适用关键词：**"改造 / 升级 / 翻新 / 对齐规范 / 重新生成"**。
+
+📖 **MUST READ** (全部必读，不得省略)：
+
+1. [boundaries.md](./boundaries.md) — 硬规则真值
+2. [foundations.md](./foundations.md) — Token 真值
+3. [components.md](./components.md) — 组件选型
+
+```
+1. 读取目标页面源码
+2. 扫描违规项（按 boundaries.md F1-F10 + S1-S8）
+3. 生成 old → new 替换清单
+   - 硬编码色值 → CSS Token 变量
+   - space-y-* → flex + gap-*
+   - w-N h-N (等值) → size-N
+   - 自定义 dark: 覆盖 → 语义 token
+4. 对照 components.md 检查组件选型是否合理（如自定义 div 改 Empty / Skeleton / Badge）
+5. 应用替换 + 输出变更报告
+```
+
+**输出**：翻新后代码 + 变更报告（每项替换的 old → new + 引用的规则 ID）。
+
+---
+
+## 3. 验证路径
+
+适用关键词：**"检查 / 验证 / 评估 / 是否符合规范"**。
+
+📖 **MUST READ** (全部必读，不得省略)：
+
+1. [boundaries.md](./boundaries.md) — 38 条硬规则
+2. [checklist.md](./checklist.md) — 10 项自检
+3. [foundations.md](./foundations.md) — Token 真值（用于校验是否符合）
+
+```
+1. 读取目标页面源码
+2. 逐条对照 boundaries.md
+   - F1-F10（禁止项）
+   - S1-S8（样式规则）
+   - C1-C12（组件结构规则）
+3. 对照 checklist.md 10 项自检
+4. 输出验证报告
+```
+
+**报告格式**：
+
+```markdown
+## 验证报告
+
+### ❌ 违规项（N）
+
+- F1 第 12 行：硬编码 `#333333` → 应改为 `text-foreground`
+- S2 第 23 行：使用 `space-y-4` → 应改为 `flex flex-col gap-4`
+- C2 第 45 行：DialogContent 缺失 DialogTitle
+
+### ⚠️ 建议项（M）
+
+- ...
+
+### ✅ 合规项（K）
+
+- ...
+```
+
+---
+
+## 4. 子任务退出条件
+
+| 任务类型 | 何时停止生成                      |
+| -------- | --------------------------------- |
+| 生成     | Step 7 自检全部通过               |
+| 翻新     | 替换清单为空 + 重新对照无违规     |
+| 验证     | 报告完整列出所有违规项 + 修复建议 |
+
+---
+
+## 5. 与 code-opentrek skill 的协作
+
+页面级任务通常**两个 skill 同时触发**。Design skill 决定"长什么样"，Code skill 决定"怎么落地"：
+
+| 决策点                   | 由谁主导                                                                               |
+| ------------------------ | -------------------------------------------------------------------------------------- |
+| 页面骨架 / Zone 划分     | design                                                                                 |
+| 组件选型                 | design                                                                                 |
+| Token 绑定 / 视觉规则    | design                                                                                 |
+| 文件放置位置             | code（[file-structure.md](../teamix-evo-code-opentrek/file-structure.md)）             |
+| import 路径 / reuse 策略 | code（[reuse-first.md](../teamix-evo-code-opentrek/reuse-first.md)）                   |
+| API / services 层        | code（[api-layering.md](../teamix-evo-code-opentrek/api-layering.md)）                 |
+| 表单实现细节             | code（[forms-and-validation.md](../teamix-evo-code-opentrek/forms-and-validation.md)） |
+
+冲突时按 ADR 0018 AI 上下文路由约定：design 决定"做什么"，code 决定"怎么做"。

package/src/teamix-evo-design-opentrek/patterns/color-mapping.md

@@ -0,0 +1,96 @@
+# Color Mapping — OpenTrek v4.1 语义色映射表
+
+> ⚠️ **Prerequisites**: 你必须由 [generation-flow.md](../generation-flow.md) Step 6（视觉填充）引导到这里，或在翻新路径中处理色彩替换时使用。
+
+> AI 在写组件代码时**只**消费下表中的 CSS 变量名，**不**直接写色值。Token 真值见 `tokens/tokens.theme.css`，本文件仅做语义到 token 名的映射。
+
+---
+
+## 1. 主色系（OpenTrek 品牌蓝）
+
+| 用途              | 变量                         | 备注                              |
+| ----------------- | ---------------------------- | --------------------------------- |
+| 主行动 / CTA 按钮 | `--color-primary`            | `#0055EE` (hsl(218.6 100% 46.7%)) |
+| primary hover     | `--color-primary-hover`      | 加深 5%                           |
+| primary pressed   | `--color-primary-pressed`    | 加深 10%                          |
+| primary 高亮辉光  | `--color-primary-glow`       | 焦点环 / 强调动效                 |
+| primary 文字色    | `--color-primary-foreground` | 主色背景上的文字（白）            |
+
+**消费规则**：
+
+- 仅用于 CTA、当前选中项、品牌标识、Switch/Checkbox 选中态
+- **禁止**用于错误态（错误用 `--color-destructive`）
+
+---
+
+## 2. 状态色（5 档体系）
+
+每种状态色提供 5 档：`--color-{X}` / `-foreground` / `-hover` / `-bg` / `-border`。
+
+| 状态          | 含义                    | 主变量                |
+| ------------- | ----------------------- | --------------------- |
+| `success`     | 成功 / 正常             | `--color-success`     |
+| `warning`     | 警告 / 待办（色相 40°） | `--color-warning`     |
+| `destructive` | 错误 / 删除 / 危险      | `--color-destructive` |
+| `info`        | 中性提示 / 引导         | `--color-info`        |
+
+**消费场景对照**：
+
+- Alert / Banner → 用 `bg-{X}-bg border-{X}-border text-{X}` 三件套
+- Status Tag / Badge → 用 `bg-{X}/10 text-{X}` 浅底深字
+- 错误输入框 → `aria-invalid:border-destructive aria-invalid:focus-visible:ring-destructive`
+
+---
+
+## 3. 灰阶语义层（gray-\* 8 级）
+
+| 用途                   | 变量                                |
+| ---------------------- | ----------------------------------- |
+| 主要灰底（卡片背景等） | `--color-gray-primary`              |
+| 主要灰底文字           | `--color-gray-primary-foreground`   |
+| 次要文字               | `--color-gray-secondary-foreground` |
+| 禁用态                 | `--color-gray-disabled`             |
+| 分隔线 / 边框          | `--color-gray-line`                 |
+| sidebar 选中底色       | `--color-gray-sidebar-accent`       |
+| 弱提示底色             | `--color-gray-muted`                |
+| 反白纯白               | `--color-gray-white`                |
+
+> 与 shadcn 标准槽（`--color-foreground` / `--color-muted` / `--color-border`）并存，提供更细粒度的引用入口。
+
+---
+
+## 4. 扩展色（accent-10）
+
+10 色调色板，用于 Tag 分类、用户头像底色、状态点等区分性场景：
+
+`--color-accent-{blue,violet,apricot,indigo,green,magenta,turquoise,orange,berry,olive}`
+
+> 选色顺序：blue → violet → apricot → indigo → green → magenta → turquoise → orange → berry → olive
+
+---
+
+## 5. 数据可视化色（chart-1..10）
+
+| 场景                    | 推荐范围               |
+| ----------------------- | ---------------------- |
+| 单系列                  | `--color-chart-1`      |
+| 2-5 系列对比            | `chart-1` … `chart-5`  |
+| 6-10 系列（异色高对比） | `chart-1` … `chart-10` |
+
+> chart-1 与 primary 同色相，确保单图表场景下视觉延续。
+
+---
+
+## 6. Sidebar / Topbar 命名空间
+
+详见 [sidebar.md §3](./sidebar.md#3-颜色映射v41-品牌化)。**不**使用主色槽（`--color-primary` 等），全部走 `--color-sidebar-*` / `--color-topbar-*`。
+
+---
+
+## 7. AI 生成自检
+
+- [ ] 没有出现 `bg-blue-{n}` / `text-red-{n}` / `text-gray-{n}` 等原始 Tailwind 色
+- [ ] 没有出现 `#xxxxxx` 十六进制硬编码
+- [ ] 没有出现 `hsl(...)` 内联值
+- [ ] sidebar 内未消费 `--color-primary`（用 `--color-sidebar-primary`）
+- [ ] 状态语义与变量对应（删除按钮用 `destructive` 而非 `warning`）

package/src/teamix-evo-design-opentrek/patterns/dashboard.md

@@ -0,0 +1,33 @@
+# Dashboard — 数据概览与监控页
+
+> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **Dashboard**，并由 Step 3 引导到这里。
+
+> AI 实操路径:Step 2(页面类型识别)判定为 Dashboard 后,本文档接管。生成频次低于 ListPage / FormPage / DetailPage,当前为最小规范,后续按 list-page.md / form-page.md 体例扩充。
+
+---
+
+## 1. 标准结构
+
+```text
+┌────────────────────────────────────────────┐
+│ PageHeader: 概览        [今日 ▼] [刷新]    │
+├────────────────────────────────────────────┤
+│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐        │
+│ │订单数│ │待办数│ │成交额│ │完成率│  ← StatCards
+│ │ 1024 │ │   3  │ │¥12.3K│ │ 68%  │        │
+│ └──────┘ └──────┘ └──────┘ └──────┘        │
+├────────────────────────────────────────────┤
+│ 业务趋势                   最近异常         │
+│ [Chart 折线图]            [Timeline]        │
+└────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 设计要点
+
+- 关键指标用 `text-3xl font-bold`,与上一周期对比用 `+/-` 配 `chart-*` 色
+- 时间范围切换持久化到 URL params
+- 图表色彩按 `chart-1` `chart-2` `chart-3` ... 顺序消费,**禁止**任意 hex
+- StatCard 数量:4 (1×4) / 6 (2×3) / 8 (2×4);超过 8 改用 ListPage
+- 不要在 Dashboard 内放可编辑表单 — 跳转 FormPage