@teamix-evo/skills 0.2.0 → 0.4.0

package/src/teamix-evo-design-uni-manager/patterns/detail-page.md

@@ -0,0 +1,224 @@
+# Detail Page — 详情页模式（uni-manager）
+
+> **触发**：用户描述含"详情/查看/信息/概览（单资源）"。
+> **核心特征**：单条记录的只读展示 + DescriptionList + 操作按钮。
+> **页面级别**：L2（面包屑模式 PageHeader，自动继承 um-topbar + Sidebar）。
+
+---
+
+## 1. 子类型识别
+
+| 子类型            | 关键词                       | 差异特征                                      |
+| ----------------- | ---------------------------- | --------------------------------------------- |
+| **标准详情**      | "详情"/"基本信息"            | PageHeader + DescriptionList + 操作按钮       |
+| **资源详情**      | "实例详情"/"资源"/"监控"     | InfoCard + MonitorPanel + Tabs（关联资源）    |
+| **跨云资源详情**  | "多云资源"/"混合云"/"跨账号" | InfoCard 顶部带 CloudBadge + 区域 Badge       |
+| **概览型**        | "概览"/"总览"                | StatCard + Chart + DescriptionList            |
+| **流程型**        | "审批"/"流程"/"记录"         | Steps + Timeline + DescriptionList            |
+| **对比型**        | "对比"/"比较"                | 双栏/多栏 DescriptionList 对照                |
+| **审计 / 日志型** | "操作日志"/"审计"            | Timeline + 过滤工具条（uni-manager 高频场景） |
+
+---
+
+## 2. 标准结构（资源详情 — uni-manager 跨云增强）
+
+```
+┌─────────────────────────────────────────────┐
+│ um-topbar (框架级)                          │
+├─────────────────────────────────────────────┤
+│ PageHeader（面包屑模式）                    │
+│ 实例与镜像 > 实例列表 > 实例详情 [创建镜像]│  ← Header
+│                                             │
+│ InfoCard ─ 基本信息                         │  ← 摘要区
+│ [☁ 阿里云] [华东1·杭州] · 资源集 · 创建人   │  ← CloudBadge + 区域
+│ 创建时间 2026-05-13                         │
+│                                             │
+│ InfoCard ─ 监控                             │
+│ [CPU 使用率] [内存使用率]（MonitorPanel）   │
+│                                             │
+│ Tabs                                        │  ← 分类
+│ [基本信息] [监控] [云盘] [安全组] [快照]    │
+│ [操作日志] ← uni-manager 默认必备           │
+│                                             │
+│ DescriptionList ─ 基本信息                  │  ← 主区
+│ 架构: X86       地域: cn-hangzhou           │
+│ 实例ID: i-xxx   状态: [Badge 运行中]        │
+│                                             │
+│ DescriptionList ─ 配置信息                  │
+│ vCPU: 2         内存: 4 GiB                 │
+└─────────────────────────────────────────────┘
+```
+
+## 简洁详情结构
+
+```
+┌─────────────────────────────────────────────┐
+│ PageHeader（面包屑模式）                    │
+│ 用户列表 > 用户详情      [编辑] [删除]      │
+│                                             │
+│ DescriptionList (column: 2, density="detail")│
+│ 姓名: 张三       邮箱: zhangsan@example.com │
+│ 角色: 管理员     状态: [Badge 启用]         │
+│ 创建时间: 2026-01-15  更新: 2026-04-20      │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 必需组件
+
+| 组件                | 位置 | 说明                            |
+| ------------------- | ---- | ------------------------------- |
+| **PageHeader**      | top  | 面包屑模式(L2 页面)+ 操作按钮组 |
+| **DescriptionList** | main | 详情页核心展示组件              |
+| **DescriptionItem** | main | 描述项最小展示单元              |
+
+**框架级**（自动继承）：um-topbar、Sidebar、PageHeader 由 page-frame 管控。
+
+### 可选组件
+
+- **InfoCard** — 顶部摘要（云厂商 + 区域 + 组织 / 创建人 / 创建时间）
+- **CloudBadge** — 跨云资源在 InfoCard / 标题旁显式标注
+- **Tabs** — 信息分多类（基本/监控/关联资源/操作日志）
+- **MonitorPanel** — CPU/内存/网络监控（仅资源详情）
+- **Badge** — 状态指示
+- **Tooltip** — 长 ID / 截断字段悬浮
+- **OperationLog** —（概念占位）操作日志 Timeline，uni-manager 高频
+
+---
+
+## 4. DescriptionItem 字段交互
+
+| 类型           | 触发       | 反馈                              |
+| -------------- | ---------- | --------------------------------- |
+| 默认展示       | —          | 只读文本，空值 `-` 占位           |
+| 可复制         | 点 📋 图标 | 图标高亮 + Toast "已复制"         |
+| 可编辑（行内） | 点 ✎ 图标  | 切换为 Input                      |
+| 链接跳转       | 点字段值   | 链接样式（VPC、安全组、关联资源） |
+| 状态展示       | —          | Badge + 语义色（不用原色）        |
+| 悬浮提示       | hover      | Tooltip 完整内容（截断时）        |
+
+**uni-manager 强化**：所有 ID / IP / Hash 字段**默认提供复制按钮**，不要用户去想"是否能复制"。
+
+---
+
+## 5. 操作按钮规则
+
+### 5.1 位置
+
+- **位置 A**：PageHeader 右侧（主操作 + 更多 Dropdown）
+- **位置 B**：DescriptionItem 内（行内编辑、复制）
+
+### 5.2 操作分级
+
+| 级别             | 适用            | 确认                      |
+| ---------------- | --------------- | ------------------------- |
+| 一级（可逆）     | 编辑、续费/降配 | 直接执行                  |
+| 二级（影响状态） | 释放、创建镜像  | Dialog 确认               |
+| 三级（不可逆）   | 删除            | Dialog + 输入资源名称确认 |
+
+> uni-manager 三级确认强化：必须**输入完整资源名称**（不接受只输 ID），文案见 brand.md §5。
+
+### 5.3 异步反馈
+
+| 操作            | Toast        | 页面                  |
+| --------------- | ------------ | --------------------- |
+| 释放 / 创建镜像 | "操作已提交" | 轮询状态              |
+| 删除            | "删除已提交" | 返回 ListPage 并刷新  |
+| 编辑保存        | "保存成功"   | 停留详情页 + 局部刷新 |
+
+---
+
+## 6. Tab 切换交互
+
+| 场景       | 行为                          |
+| ---------- | ----------------------------- |
+| 首次加载   | 默认激活第一个 Tab            |
+| Tab 切换   | 懒加载数据 + Loading          |
+| 无数据 Tab | 展示 Empty                    |
+| Tab 内列表 | 含独立 Pagination             |
+| URL 同步   | 切换同步 URL hash，刷新可保持 |
+
+**uni-manager 默认 Tab 集**：`[基本信息] [监控] [关联资源] [操作日志]`，其中"操作日志"几乎所有云资源都需要，AI 生成时**默认补齐**，除非用户明确说"不需要"。
+
+---
+
+## 7. 信息分组
+
+- DescriptionList 按 ListSection 分组（基本信息 / 配置信息 / 网络信息）
+- 每组可独立展开/收起（可选）
+- 分组间用 Divider 分隔
+- 每组内 DescriptionList 默认 `column: 2`，宽屏可至 4，移动端降为 1
+- **uni-manager 高密度**：详情页 Field 内距用 `density="detail"`（行距 12px，比 OpenTrek 更紧凑）
+
+---
+
+## 8. 嵌套约束
+
+| 父子关系                                                                                                 | 状态                                |
+| -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| um-topbar → PageContainer → ContentWrapper → Card(白卡) → PageHeader / InfoCard / Tabs / DescriptionList | ALLOW                               |
+| ContentWrapper → 业务组件（无 Card）                                                                     | **FORBID**                          |
+| Card → Card                                                                                              | **FORBID**（白卡单例）              |
+| InfoCard → DescriptionList / MonitorPanel / CloudBadge                                                   | ALLOW                               |
+| Tabs → TabPane → DescriptionList / DataTable / Timeline                                                  | ALLOW（关联资源用 DataTable）       |
+| Sidebar → DescriptionList                                                                                | **FORBID**                          |
+| PageHeader → Tabs                                                                                        | WARN（Tab 应在 PageHeader 下方）    |
+| 自建 topbar                                                                                              | **FORBID**（UM1：必须用 um-topbar） |
+
+---
+
+## 9. 禁止项
+
+| 禁项                       | 原因                                  |
+| -------------------------- | ------------------------------------- |
+| Form 直接在主内容区        | 编辑应通过 Drawer/Dialog/FormPage     |
+| DataTable 在主内容区       | 关联数据应用 Tabs 子面板              |
+| Chart 替代 DescriptionList | 图表属 Dashboard，监控用 MonitorPanel |
+| QueryFilter                | 详情页无筛选需求                      |
+| `hr` 分割线                | 用 Divider                            |
+| 跨云资源不标 CloudBadge    | 违反 UM3                              |
+| 自建 topbar                | 违反 UM1                              |
+
+---
+
+## 10. 边界情况
+
+| 场景       | 处理                    |
+| ---------- | ----------------------- |
+| 无数据     | Empty + 返回列表引导    |
+| 加载中     | Loading 骨架屏          |
+| 加载失败   | ErrorState + 重试按钮   |
+| 权限不足   | 操作按钮隐藏，只读展示  |
+| 资源不存在 | 跳转 404 ExceptionPage  |
+| 字段为空   | 展示 "-" 占位           |
+| 字段过长   | 截断 + Tooltip 完整内容 |
+| 跨账号资源 | 顶部加 [跨账号] Badge   |
+
+---
+
+## 11. 详情 → 列表返回约定
+
+- 面包屑父级项点击返回 ListPage
+- PageHeader 右侧可选 × 关闭按钮
+- 返回后 ListPage 保持原筛选 + 分页
+- 详情页编辑成功后，按业务决策：
+  - 留在详情页（Toast「保存成功」+ 局部刷新）
+  - 或返回 ListPage（Toast「保存成功」+ 列表刷新）
+
+---
+
+## 12. 详情页特有自检
+
+- [ ] PageHeader 用面包屑模式（L2 页面）
+- [ ] um-topbar 在框架层就位（UM1）
+- [ ] DescriptionList 列数：默认 2，宽屏可 4，移动端 1，详情页用 `density="detail"`
+- [ ] 关联资源用 Tabs 子面板（不在主区直接放 DataTable）
+- [ ] Badge 用语义色（不用原色）
+- [ ] 空字段用 "-" 占位
+- [ ] 长字段（ID/Hash）`font-mono` + 提供复制按钮
+- [ ] 操作分级正确（删除 = 输入资源名称确认）
+- [ ] Tab 切换 URL hash 同步
+- [ ] 跨云资源 InfoCard 标注 CloudBadge + 区域（UM3）
+- [ ] "操作日志" Tab 默认配齐
+- [ ] 边界状态完整：Empty / Loading / ErrorState / 权限不足 / 404

package/src/teamix-evo-design-uni-manager/patterns/form-page.md

@@ -0,0 +1,329 @@
+# Form Page — 表单页模式（uni-manager）
+
+> **触发**：用户描述含"新建/创建/编辑/修改/复制/填写"。
+> **核心特征**：用户输入数据 + 字段校验 + 提交。
+> **页面级别**：L2（面包屑模式 PageHeader，自动继承 um-topbar + Sidebar）。弹窗表单 = L0。
+
+---
+
+## 1. 子类型识别
+
+| 子类型          | 关键词                | 差异特征                                                   |
+| --------------- | --------------------- | ---------------------------------------------------------- |
+| **新建表单**    | "新建"/"创建"/"新增"  | 字段为空，标题"新建 XX"，保存返回列表                      |
+| **编辑表单**    | "编辑"/"修改"         | 字段填充数据，标题"编辑 XX"，保存返回原页                  |
+| **复制新建**    | "复制"/"克隆"         | 字段预填源数据（ID 除外），标题"复制新建 XX"，保存返回列表 |
+| **Drawer 内联** | "侧滑编辑"/"快速编辑" | 在列表页右侧滑出 Drawer，无路由切换（uni-manager 高频）    |
+
+### FormPage vs Wizard vs Drawer 区分
+
+| 场景                       | 类型        | 判断依据                                     |
+| -------------------------- | ----------- | -------------------------------------------- |
+| 字段无顺序依赖，一次填写   | FormPage    | 单页表单                                     |
+| 步骤间有顺序依赖，逐步完成 | WizardPage  | 多步流程，Steps                              |
+| 列表页快速编辑单条记录     | Drawer 内联 | 不切路由，保留列表上下文（uni-manager 默认） |
+
+> Wizard 是独立页面类型，不是 FormPage 子类型。Drawer 内联是**编辑表单**的视图变体。
+
+---
+
+## 2. 布局模式（三选一）
+
+### 2.1 SINGLE_COL（默认）
+
+```text
+┌────────────────────────────────────────┐
+│ um-topbar (框架级)                     │
+├────────────────────────────────────────┤
+│ PageHeader: 新建实例                   │
+│                                        │
+│ FieldGroup                             │
+│   Field [实例名称 *]                   │
+│   Field [地域            ▼]            │
+│   Field [可用区          ▼]            │
+│   Field [实例规格 *      ▼]            │
+│                                        │
+│ ─────────────────────────              │
+│ SubmitBar         [取消] [确定]        │  ← justify-end
+└────────────────────────────────────────┘
+```
+
+### 2.2 TWO_COL（多字段并排）
+
+```text
+FieldGroup
+  ┌─ 列 1 ──────┐ ┌─ 列 2 ──────┐
+  │ 用户名 *    │ │ 邮箱 *      │
+  │ 角色 *      │ │ 状态        │
+  │ 部门        │ │ 手机号      │
+  └─────────────┘ └─────────────┘
+SubmitBar  [取消] [保存]
+```
+
+### 2.3 SECTION（分区表单）
+
+```text
+Card[FieldGroup ─ 基本信息]
+  实例名称 *
+  类型 * [自研 ○ MySQL ○ PostgreSQL]
+
+Card[FieldGroup ─ 网络配置]
+  地域 *  /  VPC *  /  交换机 *
+
+Card[FieldGroup ─ 存储配置]
+  存储空间 *  /  备份策略
+
+SubmitBar  [取消] [创建]
+```
+
+**何时分区**：字段 > 10 / 业务概念分组明显 / 含可选高级配置。
+
+### 2.4 Drawer 内联（uni-manager 编辑高频）
+
+```text
+┌── 列表页（保持） ────────┐ ┌── Drawer (侧滑) ──┐
+│ DataTable                │ │ Title: 编辑 实例   │
+│ ▢ i-001 [编辑]──────────►│ │                    │
+│ ▢ i-002                  │ │ FieldGroup         │
+│ ▢ i-003                  │ │  Field 名称        │
+│                          │ │  Field 规格        │
+│                          │ │                    │
+│                          │ │ [取消] [保存]      │
+└──────────────────────────┘ └────────────────────┘
+```
+
+**适用场景**：单字段或 ≤ 5 字段编辑、不离开列表上下文、批量编辑。**字段 > 5 推荐走 FormPage 页面**。
+
+---
+
+## 3. 必需组件
+
+| 组件                  | 位置   | 说明                                  |
+| --------------------- | ------ | ------------------------------------- |
+| **PageHeader**        | top    | 面包屑模式（L2 页面）                 |
+| **Form / FieldGroup** | center | 表单容器，**禁止**用 div + space-y-\* |
+| **SubmitBar**         | bottom | 提交操作栏，居右排列                  |
+
+**框架级**（自动继承）：um-topbar、Sidebar、Breadcrumb。
+
+---
+
+## 4. SubmitBar / Footer 规则
+
+### 4.1 智能定位
+
+- Footer **从滚动区域移出**，作为 Card 的直接子元素
+- Card：`flex flex-col max-h-[calc(100vh-48px)]`
+- 内容区：`flex-1 overflow-y-auto min-h-0`
+- Footer：`flex-shrink-0 z-10 bg-card border-t`
+
+### 4.2 行为
+
+| 场景        | Card 高度                | Footer                   |
+| ----------- | ------------------------ | ------------------------ |
+| 内容 < 视口 | 自适应                   | 跟随内容自然展示         |
+| 内容 > 视口 | max-h:calc(100vh - 48px) | 固定底部，悬浮于表单上方 |
+
+### 4.3 按钮顺序（从左到右）
+
+- `[取消]` → `[上一步]`（Wizard 中）→ `[下一步 / 提交 / 保存]`
+- 主按钮始终在最右侧（Primary）
+- 容器 `justify-end`
+
+---
+
+## 5. 字段控件选型
+
+> **枚举数量阈值规则（≤7 RadioGroup / 8-30 Select / >30 Combobox）见 [components.md §3.5 输入控件](../components.md#35-输入控件--input-vs-select-vs-combobox)**。本节只列表单页专属补充字段。
+
+| 字段类型       | 组件                         | 说明                                      |
+| -------------- | ---------------------------- | ----------------------------------------- |
+| 布尔（设置）   | Switch                       | "启用 X" 类开关                           |
+| 布尔（表单）   | Checkbox                     | 协议确认                                  |
+| 单选（2~5 项） | ToggleGroup                  | 类型选择（可视化优于下拉）                |
+| 验证码         | InputOTP                     | 短信 / 邮箱 OTP                           |
+| 范围数值       | Slider                       | 资源配比 / 阈值                           |
+| 输入 + 按钮    | InputGroup                   | 复制、单位切换                            |
+| 文件上传       | FileUpload                   | 单 / 多文件                               |
+| 日期 / 时间    | DatePicker / DateRangePicker | —                                         |
+| 区域 / 可用区  | Select 联动                  | uni-manager 高频；地域改变时可用区清空    |
+| 跨云上下文     | ContextSwitcher（概念占位）  | 在 um-topbar 中已显式给出，不在表单内重复 |
+
+---
+
+## 6. 字段校验规则
+
+### 6.1 触发时机
+
+| 场景       | 触发             |
+| ---------- | ---------------- |
+| 单字段格式 | blur（失焦）     |
+| 必填检查   | submit（提交时） |
+| 跨字段联动 | change（实时）   |
+| 后端校验   | submit 提交后    |
+
+### 6.2 视觉反馈
+
+- 错误：`data-invalid` 在 Field 上、`aria-invalid` 在控件上 → 红色边框 + FormMessage 错误描述
+- 必填：label 后置 `*` 红色标记
+- 字段说明优先 Tooltip（避免行内增加阅读负担）
+- 提交失败：聚焦第一个错误字段
+- **uni-manager 锐利风**：错误边框圆角同样为 2px，不要与 OpenTrek 的 6px 混用
+
+### 6.3 长表单分组
+
+- 单组字段 ≤ 6
+- > 10 字段必须分区或分步
+- 分区用 Card 内嵌 FieldGroup
+
+---
+
+## 7. 提交交互
+
+### 7.1 操作流
+
+| 操作             | 触发         | 前置         | 反馈                                     |
+| ---------------- | ------------ | ------------ | ---------------------------------------- |
+| 保存             | 点[确定]     | 本地校验通过 | 校验 → 提交 → Toast「保存成功」          |
+| 保存失败         | 后端返回错误 | —            | 字段标红 + Toast 错误 + 留在表单         |
+| 取消（无未保存） | 点[取消]     | —            | 直接离开                                 |
+| 取消（有未保存） | 点[取消]     | —            | AlertDialog 确认离开                     |
+| 返回（面包屑）   | 点击父级     | 有未保存内容 | AlertDialog 确认                         |
+| 切租户/区域      | um-topbar    | 有未保存内容 | AlertDialog 二次确认（见 flows.md §1.E） |
+
+### 7.2 异步提交
+
+| 类型         | UI                      | 反馈                                |
+| ------------ | ----------------------- | ----------------------------------- |
+| 同步（快速） | 按钮 disabled + Spinner | Toast 结果                          |
+| 异步（耗时） | 不阻塞                  | Toast「提交成功，后台处理中」+ 轮询 |
+
+### 7.3 操作确认分级
+
+| 级别             | 适用             |
+| ---------------- | ---------------- |
+| 一级（可逆）     | 保存（校验通过） |
+| 二级（有未保存） | 取消/离开/切租户 |
+
+### 7.4 危险操作专用文案（uni-manager 强化）
+
+> 删除 / 释放 / 销毁 等不可逆操作，必须满足 brand.md §5：
+
+- 标题：陈述句"释放实例 i-xxx"，不要疑问句"确定释放？"
+- 正文：明确列出影响（"实例释放后无法恢复，关联快照将一并删除"）
+- 输入确认：要求**输入完整资源名称**（不接受 ID）
+- 主按钮：危险红 P1，文案与标题同步（如"释放"）
+
+---
+
+## 8. shadcn 表单组合契约
+
+> 表单**组合层面**的本地约定。视觉/全局规则参见 [boundaries.md FF1-FF4](../boundaries.md#ff1-ff4--表单专属硬约束)（色块、必填、Card 嵌套、错误文案）+ [boundaries.md S2](../boundaries.md#error-s2--不用-space-x---space-y--改用-flex--gap-)（gap 替代 space-y）+ [boundaries.md F8](../boundaries.md#error-f8--禁止在-dialogtitle-中加图标--scope-dialog)（DialogTitle 无图标）+ [boundaries.md F9](../boundaries.md#error-f9--弹窗确定按钮禁止加-disabled-禁用态--scope-dialog)（提交按钮无 disabled）。
+
+- **FC1 表单布局**：`FieldGroup` + `Field`，**禁止** `<div>` + `space-y-*`（并见 S2）
+- **FC2 InputGroup 内子件**：`InputGroupInput` / `InputGroupTextarea`，不用原始 `Input`
+- **FC3 输入 + 按钮**：`InputGroup` + `InputGroupAddon`
+- **FC4 2~5 选项**：`ToggleGroup`，**禁止**循环 `Button` 手动 active
+- **FC5 相关选项组**：`FieldSet` + `FieldLegend`
+- **FC6 校验态**：`data-invalid` 在 `Field`、`aria-invalid` 在控件（与 FF1 配合）
+- **反馈**：`import { toast } from "sonner"`（并见 [boundaries.md C9](../boundaries.md#warn-c9--toast-用-sonner)）
+
+---
+
+## 9. 嵌套约束
+
+| 父子关系                                                                                      | 状态                        |
+| --------------------------------------------------------------------------------------------- | --------------------------- |
+| um-topbar → PageContainer → ContentWrapper → Card(白卡) → PageHeader / FieldGroup / SubmitBar | ALLOW                       |
+| ContentWrapper → 业务组件（无 Card）                                                          | **FORBID**                  |
+| Card → Card                                                                                   | **FORBID**（白卡单例）      |
+| Card(白卡) → Card(分区)                                                                       | ALLOW（分区表单内嵌）       |
+| Card(分区) → FieldGroup                                                                       | ALLOW                       |
+| FieldGroup → Field                                                                            | ALLOW                       |
+| Field → Input / Select / Switch / ToggleGroup / Textarea                                      | ALLOW                       |
+| Field → InputGroup                                                                            | ALLOW                       |
+| Card → Form                                                                                   | **FORBID**（用 FieldGroup） |
+| Drawer → FieldGroup                                                                           | ALLOW（内联编辑）           |
+| 自建 topbar                                                                                   | **FORBID**（UM1）           |
+
+---
+
+## 10. 禁止项
+
+| 禁项                        | 原因                             |
+| --------------------------- | -------------------------------- |
+| DataTable 在主内容区        | 关联数据用 Dialog + DataTable    |
+| Chart 在表单页              | 图表属 Dashboard                 |
+| 内联 Input（不在 Field 内） | 必须 FieldGroup → Field 包装     |
+| 原始 div 表单布局           | 用 FieldGroup + Field            |
+| 单页字段 > 15 不分组        | 分区或拆 Wizard                  |
+| 自建 topbar                 | 违反 UM1                         |
+| 危险操作只用 ID 确认        | uni-manager 要求**资源名称**确认 |
+
+---
+
+## 11. 表单页特有自检
+
+- [ ] PageHeader 用面包屑模式（L2 页面）
+- [ ] um-topbar 在框架层就位（UM1）
+- [ ] 所有 Input 在 Field → FieldGroup 内（FC1）
+- [ ] data-invalid + aria-invalid 双重声明（FC6）
+- [ ] 控件按字段类型选型正确（2~5 选用 ToggleGroup，不循环 Button）
+- [ ] SubmitBar 居右 + 按钮顺序：取消 → 上一步 → 主操作
+- [ ] 长表单（> 10）分组或分区
+- [ ] 异步提交：按钮 loading + Spinner
+- [ ] 取消时未保存内容 AlertDialog 确认
+- [ ] 编辑模式加载用 Skeleton
+- [ ] Toast 用 sonner（C9），不用自定义全局通知
+- [ ] 单字段 / ≤5 字段编辑优先用 Drawer 内联，不切路由
+- [ ] 危险操作：标题陈述句 + 输入资源名称确认
+
+---
+
+## 12. 《Teamix UI 表单设计规范》对齐 Checklist
+
+> 详细说明见 [`packages/ui/AGENTS.md` 第六节](../../../../ui/AGENTS.md#六表单族硬规则formfieldfilter-barlabelinput)。本节只列 AI 写表单时的 yes/no 自检项。
+
+### 12.1 间距（11 条硬规则，§3.1）
+
+- [ ] label → input 间距：垂直 4px / 水平 16px（由 `Field.orientation` 内置，**禁止**手写 `mt-*` / `gap-3` 覆盖）
+- [ ] error → input：**0px**（`FieldError` 内置 `-mt-1`，防止抖动）
+- [ ] description → input：4px（`FieldDescription` 默认）
+- [ ] 组内行距 20px / 组间距 32px / 详情页 12px（`FieldGroup` / `FieldSection` / `density="detail"`）
+- [ ] checkbox / radio / 文字链 横向：**16px**（`gap-4`，组件内置）
+- [ ] icon 与文字 横向：**4px**（label 内 `文字 ⓘ *`，Label 组件内置）
+
+### 12.2 必填与 a11y（§一 + §六）
+
+- [ ] `*` 后置：`<FormLabel required>` / `<FieldLabel required>`，**禁止**手写 `<span>* 邮箱</span>`
+- [ ] input 同步 `aria-required="true"`，纯视觉 `*` 不替代屏幕阅读
+- [ ] invalid 单一真值在 `<Field invalid>`，自动驱动 label 着色 + FieldError 可见 + 控件 ring，**不要**重复给控件传 `aria-invalid`
+
+### 12.3 输入域宽度（5 档，§七）
+
+- [ ] 用 `Field.inputWidth="xs|s|m|l|xl"`（104/216/328/440/552px），**禁止**手写 `w-[328px]` 或 `style={{ width: 328 }}`
+- [ ] 子控件用 `style={{ width: 'var(--field-input-width)' }}` 消费
+- [ ] horizontal 模式 label 自动 `max-width = ⅓ 输入域宽`，超长 truncate（`FieldLabel` 内置）
+
+### 12.4 响应式（5 档断点，§4.1-4.2）
+
+- [ ] 多栏筛选用 `FilterBarPanel responsiveColumns={{ base, xs, s, m, l, xl }}`，**禁止**手写媒体查询 / `lg:grid-cols-*`
+- [ ] 单栏表单 < 432 自动改上下：`<Field orientation={{ base: 'vertical', xs: 'horizontal' }}>`
+- [ ] 断点用 `useBreakpoint` + `pickByBreakpoint`（`@/hooks/use-breakpoint`），**禁止**手写 `useMediaQuery`
+
+### 12.5 按钮容器感知（§六）
+
+- [ ] 用 `FormActions container="page|page-stepper|modal|drawer"` 一次性配齐 position/align/alignWithInput
+- [ ] 决策口径：页面基础/分组 → `page` / 页面分步 → `page-stepper` / 弹窗 → `modal` / 抽屉 → `drawer`
+- [ ] **禁止**裸 `<div className="flex gap-2 justify-end">` 写底部按钮
+
+### 12.6 内容截断三件套（§八）
+
+- [ ] 横向宽度受限的字段值 / 长 label / 表格单元格用 `<Ellipsis>`，**禁止**手写 `truncate` + 独立 `<Tooltip>`
+- [ ] 多行截断走 `<Ellipsis lines={2}>`，**禁止**手写 `-webkit-line-clamp`
+
+### 12.7 RHF vs Server Actions 流派（§6.1）
+
+- [ ] 用 RHF + zod → 走 `Form / FormField / FormItem / FormLabel / FormMessage`（form 包，FormItem 内部就是 Field）
+- [ ] Server Actions / 原生 form / 简单状态 → 走 `Field / FieldGroup / FieldLabel / FieldError`（field 包）
+- [ ] **禁止**两套混用（Section / Actions 是 re-export 别名，选哪边都行，**不要交叉**）