@teamix-evo/skills 0.3.0 → 0.4.0

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

@@ -0,0 +1,83 @@
+# 自检清单 · OpenTrek
+
+> AI 生成 / 翻新页面后**必须**逐项对照本清单。规则细节看 [boundaries.md](./boundaries.md)，本文件只列"要检查什么"。
+>
+> **强制项（12）必须 100% 通过**；**建议项（5）至少 4 项通过**。
+
+---
+
+## 强制项（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]      |
+
+> **强制项 #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` 类时务必核对。
+>
+> **强制项 #13([ADR 0025](../../../../../docs/adr/0025-component-props-explicit-declaration.md))**:组件 `Props` interface 必须**显式声明所有可配置 prop**,带中文 JSDoc(由 `pnpm gen:meta` 提取生成 meta.md props 表)。**禁止**空 extends 透传(如 `interface FooProps extends ComponentPropsWithoutRef<typeof Primitive.Root> {}`)— 会导致 meta props 表为空、Storybook controls 缺数据源、AI 生成代码无法读取支持的 prop。**数据录入类组件**(Checkbox/Switch/Select/Input/Slider 等)必须暴露至少一对受控套:`value` + `onChange`(或 Radix 命名 `onCheckedChange` / `onValueChange`)+ `defaultValue` / `defaultChecked`,业务侧能用受控模式跑通。
+
+[F1]: ./boundaries.md
+[ADR0023]: ../../../../../docs/adr/0023-cursor-pointer-explicit-in-component-source.md
+[S1]: ./boundaries.md
+[S2]: ./boundaries.md
+[S5]: ./boundaries.md
+[S6]: ./boundaries.md
+[S7]: ./boundaries.md
+[S8]: ./boundaries.md
+[C1-C12]: ./boundaries.md
+[C7-C12]: ./boundaries.md
+[I1-I2]: ./boundaries.md
+[philosophy]: ./philosophy.md
+
+---
+
+## 建议项（5）
+
+- 💡 11. 列表页空数据有 `<Empty>` + 主操作入口（"创建第一个 X"）
+- 💡 12. 表单字段 > 6 时用 `<Card>` 分组或 Steps 分步
+- 💡 13. 按钮文案：动宾 ≤ 5 字（"创建实例"）；危险用明确名词 + 动作（"永久删除"）；不写"OK / 确认" — 详见 [brand.md §文案语气](./brand.md#文案语气)
+- 💡 14. ID / Hash / 路径用 `font-mono` + 复制按钮
+- 💡 15. 操作 ≤ 200ms 反馈：loading / Toast / 状态变化
+
+---
+
+## 自检报告模板
+
+```markdown
+## 自检报告 — <页面名>
+
+### 强制项（10/10 通过）✅
+
+- [x] 1. 无硬编码色值
+- [x] 2. 状态用 Badge / 语义 token
+- [x] 3. 间距用 gap
+- [x] 4. className 不覆盖颜色
+- [x] 5. 复合组件结构完整
+- [x] 6. 专用组件（Badge/Skeleton/Empty/Separator/Alert/Toast）
+- [x] 7. 图标 data-icon
+- [x] 8. 无 z-index / dark: 覆盖
+- [x] 9. 条件类名用 cn()
+- [x] 10. 危险操作二次确认
+
+### 建议项（4/5 通过）✅
+
+- [x] 11. 空状态
+- [x] 12. 字段分组
+- [x] 13. 按钮文案合规
+- [ ] 14. 长字符串 mono — 第 N 行 ID 未应用 font-mono
+- [x] 15. 操作反馈
+
+### 修正建议
+
+- 第 N 行：`<span>{order.id}</span>` → `<span className="font-mono">{order.id}</span>` + `<CopyButton />`
+```

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

@@ -0,0 +1,245 @@
+# Components — 选型决策与组合规则
+
+> **本文档只回答"用什么组件、怎么搭配"，不写具体 Props / Examples / import 路径。**
+> 组件 API、Props、示例代码通过 MCP `get_component_meta` 实时查询；可用列表通过 `list_components` / `find_components` 查询。
+
+---
+
+## 0. 组件查不到时的兜底铁律（最高优先）
+
+> **本节规则优先级高于本文件其余所有条款，违反此节即视为违反 reuse-first 原则（见 `teamix-evo-code-opentrek/reuse-first.md`）。**
+
+### 0.1 触发场景
+
+调用 `list_components` / `find_components` 命中失败、或本文件提到的组件名（例如 `SearchCombo` / `ContextSwitcher` / `ItemCard` / `CardGrid` / `CardActionBar`）在 `@teamix-evo/biz-ui` 中无实物时。
+
+### 0.2 三步处置法
+
+1. **不要自造同名组件入 `src/components/`** — 即使本文件提到该组件名，也必须先确认实物存在。
+2. **改用 `@teamix-evo/ui` 中语义近似的原子组件做最小拼装**（参见本文件 §3 决策树和 §5 拼凑配方）。
+3. **在响应中显式声明替代关系**，例如：
+
+   > `// SearchCombo 暂未实物化 → 用 Input + Select + Button 拼装`
+
+### 0.3 兜底优先序
+
+```text
+biz-ui 实物组件 (优先)
+  ↓ 未命中
+ui 原子组件最小拼装 (兜底)
+  ↓ 仍无法表达
+跳转 patterns/*.md 找页面级模板
+  ↓ 仍无法表达
+回报用户：缺组件 + 已尝试拼装方案
+```
+
+**永远不要**：
+
+- 在 `src/components/` 下新增与 biz-ui 同名的"私有版本"
+- 用 antd / arco / chakra 等其它库填补缺口
+- 在 skill 响应中写"假设 biz-ui 有 X"而不实查 MCP
+
+---
+
+## 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** 等高频件。 |
+
+### 1.1 选型铁律
+
+1. **优先 biz-ui 实物层** — 已封装变体 + 文案规范，但**注意 opentrek 当前仅 2 个实物**。
+2. **biz-ui 无实物 → ui 实现层** — 89 个原子件覆盖绝大部分场景。
+3. **ui 仍无 → §5 拼凑配方** — 用 ui 多个原子件最小组合（不私造）。
+4. **禁止**自造同名组件（违反 reuse-first，详见 §0）。
+
+### 1.2 实时校验
+
+任何组件名引用前必须用 `find_components(name)` 验证存在性，**不要相信本文档中"组件名"的存在性默认**（biz-ui 处于持续物化中，本文档可能滞后）。
+
+---
+
+## 2. 必备组件 — 每个页面都需要
+
+| 组件           | 实际归属 | 何时使用         | 备注                                                       |
+| -------------- | -------- | ---------------- | ---------------------------------------------------------- |
+| **PageHeader** | ui       | 所有页面必需     | L1 用 title 模式、L2 用 breadcrumb 模式（二选一，不并存）  |
+| **op-sidebar** | biz-ui   | TWO_COL 布局必需 | 含顶部 Logo + 产品名；768px 以下自动折叠为抽屉             |
+| **Button**     | ui       | 所有交互页面     | 主操作 ≤ 1 个（Primary）；次要 Secondary；危险 Destructive |
+
+> `op-sidebar` 是 opentrek variant 唯一的导航实物组件。如需顶部栏 / 横向布局 → 用 ui `navigation-menu` + `app` 组合。
+
+---
+
+## 3. 选型决策树
+
+### 3.1 反馈与确认 — Dialog vs Sheet vs Drawer vs Popover
+
+```text
+需要用户做出决定 / 阻塞主流程？
+├─ 是 → 用 Dialog
+│   ├─ 简单确认（删除/退出）→ AlertDialog
+│   └─ 复杂表单（< 8 字段）→ Dialog
+└─ 否
+    ├─ 临时编辑/筛选（侧边滑出）→ Sheet
+    ├─ 多级下探查看（侧边可叠层）→ Drawer
+    ├─ 内容预览/上下文操作（小气泡）→ Popover
+    └─ 仅展示信息（鼠标悬浮）→ Tooltip
+```
+
+**容量决策**：
+
+- 字段 ≥ 8 个 / 内容超过 1 屏 → **跳转 FormPage**（不要塞进 Dialog）
+- 字段 4~8 个 → Sheet（侧边可保留上下文）
+- 字段 ≤ 4 个 → Dialog
+- **任务层级 ≤ 3 层**（Teamix-UI 容器规范）— 超过则强制跳页
+
+### 3.2 容器选型 — 操作型 vs 展示型
+
+> 来源：Teamix-UI 容器规范。
+
+| 类别       | 容器                                            | 何时使用                                         |
+| ---------- | ----------------------------------------------- | ------------------------------------------------ |
+| **操作型** | 全页面（FormPage）                              | 字段多 / 步骤多 / 需要持久 URL                   |
+| **操作型** | 弹窗模态（Dialog）                              | 阻塞主流程的简短确认或表单；最多 2 级，不再深入  |
+| **操作型** | 气泡（Popconfirm）                              | 二次确认（删除/解绑），轻量提示                  |
+| **展示型** | 全页面（DetailPage）                            | 完整信息查看，路由可分享                         |
+| **展示型** | 抽屉非模态（Sheet）                             | 不阻塞主流程，可保留上下文（如侧栏 Detail）      |
+| **展示型** | 抽屉模态（Drawer）                              | 多级下探查看（如资源 → 子资源 → 配置），逐层推出 |
+| **展示型** | 弹窗模态（Dialog）                              | 一次性展示重要信息                               |
+| **展示型** | 卡片（Card）                                    | 同级信息分组；卡片之间间距 16px                  |
+| **展示型** | 通知反馈（Toast/Sonner / Alert / Notification） | 瞬时反馈 / 页面级横幅 / 系统通知                 |
+
+### 3.3 状态展示 — Badge vs Tag vs Alert
+
+| 组件               | 用途                             | 容器                |
+| ------------------ | -------------------------------- | ------------------- |
+| **Badge**          | 状态标记（启用/停用、成功/失败） | 表格列、详情字段    |
+| **Tag**            | 业务分类（标签、关键字）         | 多个并列时使用      |
+| **Alert**          | 页面级提示（操作结果、系统通知） | 页面顶部、Form 顶部 |
+| **Toast / Sonner** | 瞬时反馈（保存成功）             | 全局浮层            |
+
+**铁律**：状态颜色用 `bg-{success|warning|destructive|info}/10` 而非 `bg-red-500`（参见 `boundaries.md` S8）。
+
+### 3.4 数据展示 — Table vs DataTable vs Card vs List
+
+```text
+数据量 ≤ 50 / 列数 ≤ 6 → Table
+数据量 > 50 / 列数 > 6 → DataTable（含虚拟滚动 + 排序 + 列控制）
+卡片化展示（含图片/丰富信息）→ list-card（biz-ui 实物）或 Card[] + Grid 拼装
+简单单列列表 → 普通 div + map（不必造组件）
+```
+
+**列上限**：建议表格 ≤ 6 列，超过用 DataTable 的列控制（参见 `patterns/list-page.md`）。
+
+### 3.5 导航 — Tabs vs Sidebar vs Breadcrumb vs Steps
+
+| 场景                | 组件                                 | 归属   |
+| ------------------- | ------------------------------------ | ------ |
+| 详情页内子模块切换  | **Tabs**                             | ui     |
+| 同级页面切换        | **op-sidebar**                       | biz-ui |
+| 父子页面层级        | **Breadcrumb**（由 PageHeader 内置） | ui     |
+| 多步流程            | **Steps**                            | ui     |
+| 步骤数 ≤ 3 且无依赖 | 不用 Steps，用单页 Form              | —      |
+
+### 3.6 输入控件 — Input vs Select vs Combobox
+
+```text
+枚举值 ≤ 7 → RadioGroup（一屏可见）
+枚举值 8~30 → Select
+枚举值 > 30 / 需搜索 → Combobox（= ui command）
+多选 → MultiSelect / Checkbox
+日期 → DatePicker / DateRangePicker
+富文本 → Textarea / RichEditor
+文件 → Upload
+自动补全 → AutoComplete
+```
+
+---
+
+## 4. 复合组件结构铁律
+
+> **完整规则在 `boundaries.md` C1-C12，此处仅列高频项**
+
+| 组件       | 必备子结构                                                          | 缺失后果           |
+| ---------- | ------------------------------------------------------------------- | ------------------ |
+| **Dialog** | `DialogHeader > DialogTitle` 必须存在                               | 屏幕阅读器无法识别 |
+| **Sheet**  | `SheetHeader > SheetTitle` 必须存在                                 | 同上               |
+| **Form**   | `FormField > FormItem > FormLabel + FormControl + FormMessage` 全套 | 无错误提示渲染     |
+| **Tabs**   | `TabsTrigger` 必须在 `TabsList` 内                                  | 渲染异常           |
+| **Select** | `SelectTrigger > SelectValue` + `SelectContent > SelectItem`        | 无法触发           |
+| **Card**   | `CardHeader > CardTitle` + `CardContent`                            | 字号 / 间距错乱    |
+
+---
+
+## 5. 业务扩展层（候补）— 实物 vs 概念 + 拼凑配方
+
+> opentrek variant 当前**只有 2 个**实物业务组件：`list-card`、`op-sidebar`。
+> 以下表格区分"已实物化"与"概念占位（用 ui 拼装）"。
+
+### 5.1 已实物化（直接使用）
+
+| 组件           | 用途                              | 归属            |
+| -------------- | --------------------------------- | --------------- |
+| **list-card**  | 列表页卡片化展示（替代 ItemCard） | biz-ui/opentrek |
+| **op-sidebar** | 主导航侧栏                        | biz-ui/opentrek |
+
+### 5.2 概念占位（按配方拼装）
+
+> 这些是 design 语义概念，**不是**可 import 的组件。出现下表名称时按"拼装配方"使用 ui 原子件。
+
+| 概念                | 拼装配方（ui 原子件）                                                             | 触发场景                     |
+| ------------------- | --------------------------------------------------------------------------------- | ---------------------------- |
+| **SearchCombo**     | `Input + Select + Button` 或直接用 `filter-bar`                                   | 列表页头部筛选 + 搜索        |
+| **ContextSwitcher** | `dropdown-menu + avatar`（顶部）或 `command + popover`（带搜索）                  | 多租户 / 多环境 / 多项目切换 |
+| **ItemCard**        | `card`（CardHeader + CardContent + CardFooter）；首选 biz-ui `list-card` 已实物化 | 卡片化数据项                 |
+| **CardGrid**        | `grid` + `card[]`（Tailwind grid-cols-N + gap-4）                                 | 卡片网格列表                 |
+| **CardActionBar**   | `card` 的 Footer 内放 `button[]`（主 + 次 + 危险）                                | 卡片底部操作区               |
+
+**使用要求**：
+
+- 拼装时遵守 §3 决策树和 `boundaries.md` 复合结构铁律（C1-C12）。
+- 拼装代码中必须加注释 `// {Concept} 暂未实物化 → ui 原子件拼装`。
+- 严禁在 `src/components/` 下新建同名文件"沉淀"该拼装，否则违反 §0 兜底铁律。
+
+---
+
+## 6. 图标 (Icons)
+
+> **完整规则见 [`boundaries.md` I1-I4](./boundaries.md#i1-i4--图标规则)** — I1 data-icon 定位、I2 不设尺寸类、I3 作为组件对象传递、I4 按 iconLibrary 导入。
+
+仅补充组件选型相关：**状态图标**统一选用 lucide-react 的 Check / X / AlertTriangle / Info（成功 / 失败 / 警告 / 信息）。
+
+---
+
+## 7. 与 MCP 工具的协作
+
+```text
+当 AI 决定使用某组件后：
+  ├── 通过 list_components({ status: "stable" }) 确认组件可用
+  ├── 通过 get_component_meta("dialog") 获取：
+  │     - Props 完整签名（required / optional / default）
+  │     - 子组件层级（DialogHeader/Footer/Title/...）
+  │     - 标准用法 Example
+  │     - 常见错误（compositionPitfalls）
+  ├── 通过 find_components("filter") 模糊搜索（不确定名称时）
+  └── 通过 tokens_get() 获取最新 token 别名（颜色/间距/圆角）
+```
+
+**约束**：在 skill 中**不写**具体 import 路径与 Props 示例 —— 这些由 MCP runtime 提供，避免 skill 与组件库版本错位。
+
+---
+
+## 8. 选型自检
+
+通用结构性规则 → 见 [checklist.md](./checklist.md)（C1-C12 / I1-I4）。本文件特有的"选型决策"自检：
+
+- [ ] 已先用 `find_components` 验证组件存在性（不靠默认）
+- [ ] biz-ui 命中失败 → 改用 ui 原子件，按 §5.2 配方拼装并加注释
+- [ ] 反馈 / 确认场景按容量选 Dialog / Sheet / Drawer / Popover
+- [ ] 容器层级 ≤ 3，弹窗最多 2 级，超过则跳转全页面
+- [ ] 卡片列表优先 biz-ui `list-card`，否则用 `card[] + grid` 拼
+- [ ] 表格 ≤ 6 列，超过改 DataTable + 列控制
+- [ ] 不存在的组件**绝不**自造，**绝不**写"假设有 X"

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

@@ -0,0 +1,51 @@
+# Flows — 用户旅程
+
+> **页间流转视图见 [`patterns/page-types.md §6 页间流转`](./patterns/page-types.md#6-页间流转)** — 包含后台主流转图、流转设计规则、资源生命周期、CRUD 流转速查。本文档只承载"四条核心用户旅程"的编织视角。
+
+---
+
+## 1. 四条核心旅程速查 + 设计要点
+
+### A · 资源查找与操作
+
+`Sidebar → ListPage(SearchCombo) → 行内操作 → 反馈(Toast / AlertDialog → Toast) → 状态自动刷新`
+
+- 搜索框必须保留焦点
+- 危险操作的 AlertDialog 必须列出**资源标识**与**影响范围**
+
+### B · 资源创建
+
+`ListPage → FormPage(分组 + 实时校验) → 提交 → 列表(顶部)`
+
+- blur 校验单字段,submit 校验全部
+- 失败**不清空表单**,错误定位到字段
+- 长表单(> 10 字段)必须有"保存草稿"
+- 创建成功落点优先返回列表,编辑成功优先停留原页
+
+### C · 异常处理
+
+`Dashboard(StatCard) → ListPage(?status=error) → DetailPage(明细+日志) → AlertDialog 修复 → Toast`
+
+- 异常数字必须是**可点击的钻取入口**
+- LogViewer 默认定位到异常时间点 ± 5 分钟
+- 修复操作必须显示**预期影响范围**
+
+### D · 批量操作
+
+`Checkbox 选 → BulkActionBar → AlertDialog(列出受影响资源) → 进度 → Toast(成功 N / 失败 M)`
+
+- BulkActionBar 浮动在表格底部
+- AlertDialog 必须列出至少前 5 条受影响资源
+- 部分失败时,失败项显示"重试"按钮
+
+---
+
+## 2. 流转自检
+
+- [ ] 任意页面都能通过面包屑 / Esc 返回上一级
+- [ ] ListPage 的筛选条件持久化到 URL Params(刷新 / 分享 / 返回保留)
+- [ ] FormPage 未保存离开有 Dialog 确认
+- [ ] 危险操作的 Dialog 列出影响范围与资源清单
+- [ ] 成功 / 失败页面都有"下一步"按钮(无死胡同)
+- [ ] 批量操作进度可见、部分失败可重试
+- [ ] 异常数字是可点击的钻取入口(Dashboard → ListPage 预筛选)

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

@@ -0,0 +1,271 @@
+# Foundations — 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 强制。