@teamix-evo/skills 0.4.0 → 0.6.0

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

@@ -1,289 +1,498 @@
-# Form Page — 表单页模式
-
-> **触发**：用户描述含"新建/创建/编辑/修改/复制/填写"。
-> **核心特征**：用户输入数据 + 字段校验 + 提交。
-> **页面级别**：L2（面包屑模式 PageHeader，自动继承 Sidebar）。弹窗表单 = L0。
-
 ---
-
-## 1. 子类型识别
-
-| 子类型       | 关键词               | 差异特征                                                   |
-| ------------ | -------------------- | ---------------------------------------------------------- |
-| **新建表单** | "新建"/"创建"/"新增" | 字段为空，标题"新建 XX"，保存返回列表                      |
-| **编辑表单** | "编辑"/"修改"        | 字段填充数据，标题"编辑 XX"，保存返回原页                  |
-| **复制新建** | "复制"/"克隆"        | 字段预填源数据（ID 除外），标题"复制新建 XX"，保存返回列表 |
-
-### FormPage vs Wizard 区分
-
-| 场景                       | 类型       | 判断依据                 |
-| -------------------------- | ---------- | ------------------------ |
-| 字段无顺序依赖，一次填写   | FormPage   | 单页表单                 |
-| 步骤间有顺序依赖，逐步完成 | WizardPage | 多步流程,Steps           |
-
-> Wizard 是独立页面类型，不是 FormPage 子类型。
-
+name: page-rule-form
+parent: page-rule-system
+description: >
+  表单页(PageType: FormPage)模版规则。包含表单页类型定义、子类型识别、属性模型、
+  标准布局骨架、组件推荐规则及约束、页面交互补充。基于 @teamix-evo/ui 表单规范构建。
+  触发：需要表单页规则、匹配表单页模板、生成表单页。
+  Version: 7.0
 ---
 
-## 2. 布局模式（三选一）
-
-### 2.1 SINGLE_COL（默认）
-
-```text
-┌────────────────────────────────────────┐
-│ PageHeader: 新建实例                   │
-│                                        │
-│ FieldGroup                             │
-│   Field [实例名称 *]                   │
-│   Field [地域            ▼]            │
-│   Field [可用区          ▼]            │
-│   Field [实例规格 *      ▼]            │
-│                                        │
-│ ─────────────────────────              │
-│ SubmitBar         [取消] [确定]         │  ← justify-end
-└────────────────────────────────────────┘
-```
+# 表单页技能
 
-### 2.2 TWO_COL（多字段并排）
+> ⚠️ **本文件是高阶路由索引 + 表单页高阶规则。** > **生成页面时必须读取**：
+>
+> - `../pages/form-page/SKILL.md` — 子技能入口（子类型列表 + 完整布局骨架 + 字段嵌套约束）
+> - `../rules/component-specs.json` — 表单控件 / Steps 等组件精确尺寸约束
+>
+> 本文件仅用于：(1) 了解表单页子类型概览 (2) 快速判断 FormPage vs WizardPage
 
-```text
-FieldGroup
-  ┌─ 列 1 ──────┐ ┌─ 列 2 ──────┐
-  │ 用户名 *    │ │ 邮箱 *      │
-  │ 角色 *      │ │ 状态        │
-  │ 部门        │ │ 手机号      │
-  └─────────────┘ └─────────────┘
-SubmitBar  [取消] [保存]
-```
+## 1. 页面类型定义
 
-### 2.3 SECTION（分区表单）
+**页面类型**: FormPage
+**核心特征**: 用户输入数据 + 字段校验 + 提交
+**识别条件**: 页面包含输入控件（Input/Select/Switch 等）+ 校验规则 + 提交/取消按钮
 
-```text
-Card[FieldGroup ─ 基本信息]
-  实例名称 *
-  类型 * [自研 ○ MySQL ○ PostgreSQL]
+## 2. 页面子类型识别规则
 
-Card[FieldGroup ─ 网络配置]
-  地域 *  /  VPC *  /  交换机 *
+| 子类型   | 识别关键词           | 差异特征                                                     |
+| -------- | -------------------- | ------------------------------------------------------------ |
+| 新建表单 | "新建"/"创建"/"新增" | 所有字段为空，标题"新建 XX"，保存成功返回列表                |
+| 编辑表单 | "编辑"/"修改"        | 所有字段填充数据，标题"编辑 XX"，保存后返回原页面            |
+| 复制新建 | "复制"/"克隆"        | 字段预填源数据（ID 除外），标题"复制新建 XX"，保存后返回列表 |
 
-Card[FieldGroup ─ 存储配置]
-  存储空间 *  /  备份策略
+### FormPage vs WizardPage 区分
 
-SubmitBar  [取消] [创建]
-```
+| 场景                         | 页面类型   | 核心组件                             | 判断依据                       |
+| ---------------------------- | ---------- | ------------------------------------ | ------------------------------ |
+| 单页表单（所有字段同时可见） | FormPage   | Form, FieldGroup, SubmitBar          | 字段无顺序依赖，一次性填写提交 |
+| 分步流程（多个有序步骤）     | WizardPage | Steps (C27), StepForm, NavigationBar | 步骤间有顺序依赖，需逐步完成   |
 
-**何时分区**：字段 > 10 / 业务概念分组明显 / 含可选高级配置。
+> **注意**：WizardPage 是独立的页面类型，不是 FormPage 的子类型。如需设计分步表单，请参考：
+>
+> - 页面类型定义：`rules/page-types.json` → WizardPage
+> - 组件规范：`rules/component-specs.json` → C27-Steps
+> - 示例实现：`page-rule-examples/wizard-form-page.html`
 
----
+## 3. 页面属性模型
 
-## 3. 必需组件
+| 属性            | 值                                               | 说明                                                                                                             |
+| --------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| layout.type     | SINGLE_COL / GRID                                | 简单表单 SINGLE_COL，多列表单 GRID                                                                               |
+| layout.frame    | L2                                               | 表单页为 L2 级页面，自动继承 Sidebar（含 Logo+产品名），PageHeader 使用面包屑基础组件模式                        |
+| responsive      | Desktop: 单列/多列, Tablet: 单列, Mobile: 不推荐 |
+| form.layout     | SINGLE_COL(默认), TWO_COL(多字段), SECTION(分区) |
+| submit.position | bottom                                           | flex 布局，所有行动点居右排列（justify-content: flex-end），按钮从左到右顺序：取消 → 上一步（如有）→ 下一步/提交 |
 
-| 组件                  | 位置   | 说明                                  |
-| --------------------- | ------ | ------------------------------------- |
-| **PageHeader**        | top    | 面包屑模式(L2 页面)                   |
-| **Form / FieldGroup** | center | 表单容器,**禁止**用 div + space-y-\*  |
-| **SubmitBar**         | bottom | 提交操作栏,居右排列                   |
+> **框架组件自动继承**：Sidebar、Breadcrumb 由 `rules/page-frame.json` 统一管理，L2 级页面自动包含。弹窗表单（Dialog/FormPage）为 L0 级，无框架组件。
 
-**框架级**(自动继承):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`
-
----
+## 4. 标准布局骨架
 
-## 5. 字段控件选型
+### 模式：单列表单（SINGLE_COL）
 
-> **枚举数量阈值规则(≤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 | —                        |
-
----
-
-## 6. 字段校验规则
+```
+┌─────────────────────────────────────────────────────────┐
+│  ┌─ Card(白卡容器) ──────────────────────────────────┐  │
+│  │  PageHeader (面包屑模式)
+│  │   新建实例                                │  │
+│  │  Form (SINGLE_COL)                                   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  │ 实例名称 *                                  │   │  │
+│  │  │ ┌───────────────────────────────────────┐   │   │  │
+│  │  │ │ 请输入实例名称                         │   │   │  │
+│  │  │ └───────────────────────────────────────┘   │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  │ 地域                                        │   │  │
+│  │  │ ┌───────────────────────────────────────┐   │   │  │
+│  │  │ │ 华东 1(杭州)                     ▼   │   │   │  │
+│  │  │ └───────────────────────────────────────┘   │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  │ 可用区                                      │   │  │
+│  │  │ ┌───────────────────────────────────────┐   │   │  │
+│  │  │ │ 杭州 可用区 G                    ▼   │   │   │  │
+│  │  │ └───────────────────────────────────────┘   │   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  实例规格 *                                      │   │  │
+│  │  ┌─────────────────────────────────────────┐    │   │  │
+│  │  │ ecs.c6.large                        ▼  │    │   │  │
+│  │  └─────────────────────────────────────────┘    │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  监控 *                                          │   │  │
+│  │  ┌─────────────────────────────────────────┐    │   │  │
+│  │  │ ○ 开通                                    │    │   │  │
+│  │  └─────────────────────────────────────────┘    │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  │  ─────────────────────────                           │  │
+│  │  SubmitBar (底部操作栏, 居右)                           │  │
+│  │                            [取消] [确定]              │  │
+│  └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
 
-### 6.1 触发时机
+### 模式：两列表单（TWO_COL）
 
-| 场景       | 触发             |
-| ---------- | ---------------- |
-| 单字段格式 | blur（失焦）     |
-| 必填检查   | submit（提交时） |
-| 跨字段联动 | change（实时）   |
-| 后端校验   | submit 提交后    |
+```
+┌─────────────────────────────────────────────────────────┐
+│  ┌─ Card(白卡容器) ──────────────────────────────────┐  │
+│  │  PageHeader (面包屑模式)
+│  │   编辑用户                                │  │
+│  │  Form (TWO_COL)                                     │  │
+│  │  ┌────── 列 1 ──────┐ ┌────── 列 2 ──────┐         │  │
+│  │  │ 用户名 *          │ │ 邮箱 *            │         │  │
+│  │  │ [_______________]│ │ [_______________] │         │  │
+│  │  │ 角色 *           │ │ 状态              │         │  │
+│  │  │ [选择 ▼]         │ │ [● 启用 ○ 禁用]   │         │  │
+│  │  │ 部门             │ │ 手机号码          │         │  │
+│  │  │ [选择 ▼]         │ │ [_______________] │         │  │
+│  │  └──────────────────┘ └──────────────────┘         │  │
+│  │  ─────────────────────────                           │  │
+│  │  SubmitBar (居右)                                      │  │
+│  │                            [取消] [保存]             │  │
+│  └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
 
-### 6.2 视觉反馈
+### 模式：分区表单（SECTION）
 
-- 错误：`data-invalid` 在 Field 上、`aria-invalid` 在控件上 → 红色边框 + FormMessage 错误描述
-- 必填：label 后置 `*` 红色标记
-- 字段说明优先 Tooltip（避免行内增加阅读负担）
-- 提交失败：聚焦第一个错误字段
+```
+┌─────────────────────────────────────────────────────────┐
+│  ┌─ Card(白卡容器) ──────────────────────────────────┐  │
+│  │  PageHeader (面包屑模式)
+│  │   创建数据库                              │  │
+│  │  Form (SECTION)                                     │  │
+│  │  ┌─── 基本信息 ───────────────────────────────┐    │  │
+│  │  │ 实例名称 *                                 │    │  │
+│  │  │ ┌──────────────────────────────────────┐  │    │  │
+│  │  │ │ 请输入实例名称                       │  │    │  │
+│  │  │ └──────────────────────────────────────┘  │    │  │
+│  │  │ 类型 *                                    │    │  │
+│  │  │ [自研 ○ MySQL ○ PostgreSQL ○ Redis]       │    │  │
+│  │  └───────────────────────────────────────────┘    │  │
+│  │  ┌─── 网络配置 ───────────────────────────────┐    │  │
+│  │  │ 地域 *                                     │    │  │
+│  │  │ [选择 ▼]                                   │    │  │
+│  │  │ VPC *                                      │    │  │
+│  │  │ [选择 ▼]                                   │    │  │
+│  │  │ 交换机 *                                   │    │  │
+│  │  │ [选择 ▼]                                   │    │  │
+│  │  └───────────────────────────────────────────┘    │  │
+│  │  ┌─── 存储配置 ───────────────────────────────┐    │  │
+│  │  │ 存储空间 *                                 │    │  │
+│  │  │ [ 100 ] GB                                 │    │  │
+│  │  │ 备份策略                                   │    │  │
+│  │  │ [● 自动 ○ 手动]                            │    │  │
+│  │  └───────────────────────────────────────────┘    │  │
+│  │  ─────────────────────────                          │  │
+│  │  SubmitBar (居右)                                     │  │
+│  │                            [取消] [创建]            │  │
+│  └───────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
 
-### 6.3 长表单分组
+### SubmitBar / Footer 定位规则
+
+表单页（FormPage）的 SubmitBar 采用 **智能定位** 策略：
+
+**布局结构**：
+
+- Footer（SubmitBar）从滚动区域（card-scrollable）中 **移出**，作为 Card 的 **直接子元素**
+- Card 使用 `display: flex; flex-direction: column`
+- card-scrollable 使用 `flex: 1 1 auto; overflow-y: auto; min-height: 0`
+- Footer 使用 `flex-shrink: 0` 固定高度
+
+**行为定义**：
+| 场景 | Card 高度 | Footer 位置 | 内容区 |
+|------|----------|------------|--------|
+| 浏览器高度 ≥ 内容总高度 | 内容自适应（不拉伸） | 跟随表单内容自然展示 | 无滚动 |
+| 浏览器高度 < 内容总高度 | `max-height: calc(100vh - 2 × page-container-padding)` | 固定在 Card 底部，悬浮于表单上方 | 内容区滚动 |
+
+**CSS 模板**：
+
+```css
+.card {
+  display: flex;
+  flex-direction: column;
+  max-height: calc(100vh - 48px);
+}
+.card-scrollable {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  min-height: 0;
+}
+.settings-footer {
+  flex-shrink: 0;
+  z-index: 10;
+  background: hsl(var(--card));
+  border-top: 1px solid hsl(var(--gray-line));
+}
+```
 
-- 单组字段 ≤ 6
-- > 10 字段必须分区或分步
-- 分区用 Card 内嵌 FieldGroup
+**参考**：与 Dialog/Sheet Footer 的固定底部策略一致（component-specs.json C18/C19）。
+
+### Settings Section 样式规范
+
+| 属性               | 值                                            | 说明                             |
+| ------------------ | --------------------------------------------- | -------------------------------- |
+| Section padding    | `var(--card-gap) 0` (16px 0)                  | 上下内边距                       |
+| Section 间分割线   | `border-top: 1px solid hsl(var(--gray-line))` | 仅 Section 之间有分割线          |
+| Section 标题字号   | 16px                                          | —                                |
+| Section 标题字重   | 600 (semibold)                                | —                                |
+| Section 标题颜色   | `hsl(var(--gray-title))`                      | —                                |
+| Section 标题下间距 | 12px (--gap-lg)                               | margin-bottom                    |
+| Section 描述字号   | 13px (--font-size-sm)                         | —                                |
+| Section 描述颜色   | `hsl(var(--gray-secondary))`                  | —                                |
+| Section 描述下间距 | 20px (--gap-xl)                               | margin-bottom，距第一个 form-row |
+
+## 5. 组件推荐规则及约束
+
+### 必需组件
+
+| 组件       | 引用       | 层级     | 位置   | 说明                            |
+| ---------- | ---------- | -------- | ------ | ------------------------------- |
+| PageHeader | —          | ORGANISM | top    | 页面标题（如"新建实例"）        |
+| Form       | FieldGroup | ORGANISM | center | 表单容器，替代 div + space-y-\* |
+| SubmitBar  | —          | ORGANISM | bottom | 提交操作栏，底部固定            |
+
+> **框架级组件**（自动继承，无需在此声明）：Sidebar、Breadcrumb 由 `rules/page-frame.json` 统一管理，L2 级页面自动包含。弹窗表单（Dialog 内）为 L0 级，无框架组件。
+
+### 可选组件
+
+| 组件        | 引用        | 条件           | 说明                   |
+| ----------- | ----------- | -------------- | ---------------------- |
+| Select      | Select      | 下拉选择字段   | 地域、类型等预定义选项 |
+| Combobox    | Combobox    | 可搜索下拉     | 数据量大的选项         |
+| Switch      | Switch      | 布尔字段(设置) | 监控、备份等开关       |
+| Checkbox    | Checkbox    | 布尔字段(表单) | 协议确认等             |
+| RadioGroup  | RadioGroup  | 单选(少量)     | 类型选择               |
+| ToggleGroup | ToggleGroup | 2-5 选项切换   | 替代 Button 循环       |
+| InputOTP    | InputOTP    | 验证码输入     | 短信/邮箱验证          |
+| Textarea    | Textarea    | 多行文本       | 描述、备注             |
+| Slider      | Slider      | 范围选择       | 数值范围调节           |
+| Dialog      | Dialog      | 删除/二次确认  | 取消时弹窗确认         |
+| Badge       | Badge       | 状态标识       | 字段状态标记           |
+| Tooltip     | Tooltip     | 字段说明       | 复杂字段悬浮提示       |
+| Alert       | Alert       | 操作提示       | 危险操作预警           |
+| Sonner      | Sonner      | 操作反馈       | 保存成功/失败          |
+| Separator   | Separator   | 分区之间       | 替代 hr                |
+| Skeleton    | Skeleton    | 加载时         | 编辑模式加载数据时     |
+
+### 禁止组件
+
+> **枚举数量阈值规则(≤7 RadioGroup / 8-30 Select / >30 补搜索候选)见 [components.md §3.5 输入控件](../components.md#35-输入控件--input-vs-select-vs-autocomplete)**。
+
+| 组件              | 约束                     | 原因                                        |
+| ----------------- | ------------------------ | ------------------------------------------- |
+| DataTable         | 禁止出现在表单页主内容区 | 如需选择关联数据，用 Dialog + DataTable     |
+| Chart             | 禁止出现在表单页         | 图表属于 Dashboard                          |
+| PageContainer     | 禁止嵌套                 | 见 `rules/layout-rules.json`                |
+| ListPage          | 禁止嵌套                 | 表单页是页面级组件                          |
+| 内联 Input        | 禁止不在 Field 内        | 所有 Input 必须在 FieldGroup → Field 内(F1) |
+| 原始 div 表单布局 | 禁止                     | 用 FieldGroup + Field 替代(F1)              |
+
+### 嵌套约束
+
+| 父子关系                                                          | 状态   | 说明                                   |
+| ----------------------------------------------------------------- | ------ | -------------------------------------- |
+| PageContainer → ContentWrapper                                    | ALLOW  | 右侧内容大容器（必需）                 |
+| ContentWrapper → Card(白卡容器)                                   | ALLOW  | 白色卡片容器，包裹所有业务内容（必需） |
+| Card(白卡容器) → Breadcrumb                                       | ALLOW  | 标准结构                               |
+| Card(白卡容器) → PageHeader                                       | ALLOW  | 标准结构                               |
+| Card(白卡容器) → FieldGroup                                       | ALLOW  | 表单容器                               |
+| Card(白卡容器) → SubmitBar                                        | ALLOW  | 底部提交栏                             |
+| ContentWrapper → PageHeader / Breadcrumb / FieldGroup / SubmitBar | FORBID | 业务组件必须经过白卡容器包裹           |
+| Card(白卡容器) → Card(白卡容器)                                   | FORBID | 白卡容器为单例，禁止嵌套               |
+| FieldGroup → Field                                                | ALLOW  | 表单字段                               |
+| Field → Input/Select/Switch                                       | ALLOW  | 表单控件                               |
+| Field → ToggleGroup                                               | ALLOW  | 选项组控件                             |
+| Field → Textarea                                                  | ALLOW  | 多行文本                               |
+| Card(白卡容器) → Card(分区)                                       | ALLOW  | 分区表单（内部卡片）                   |
+| Card(分区) → FieldGroup                                           | ALLOW  | 分区内表单                             |
+| Card(白卡容器) → Dialog                                           | WARN   | 取消确认弹窗由全局状态管理             |
+| Card(白卡容器) → Form                                             | FORBID | Form 应在 FieldGroup 层级              |
+| Field → InputGroup                                                | ALLOW  | 输入框组（验证码等场景）               |
+
+## 6. 页面交互补充
+
+### 6.1 字段校验
+
+| 场景         | 触发      | 视觉反馈            | @teamix-evo/ui 规范                              |
+| ------------ | --------- | ------------------- | ------------------------------------------------ |
+| 必填字段为空 | 失焦/提交 | 红色边框 + 错误提示 | data-invalid on Field, aria-invalid on Input(F6) |
+| 格式错误     | 失焦/提交 | 红色边框 + 错误描述 | data-invalid + FieldDescription 展示错误(F6)     |
+| 后端校验失败 | 提交后    | 字段标红 + 错误提示 | data-invalid on Field(F6)                        |
+
+### 6.2 控件选型
+
+| 字段场景       | @teamix-evo/ui 组件 | 规范引用       |
+| -------------- | ------------------- | -------------- |
+| 文本输入       | Input               | F1             |
+| 下拉选择       | Select              | C1(Group 嵌套) |
+| 可搜索下拉     | Combobox            | —              |
+| 布尔开关(设置) | Switch              | F1             |
+| 复选框(表单)   | Checkbox            | F1,F5          |
+| 单选(2-5 项)   | ToggleGroup         | F4             |
+| 单选(>7 项)    | RadioGroup          | F1,F5          |
+| 验证码         | InputOTP            | —              |
+| 多行文本       | Textarea            | F2             |
+| 范围选择       | Slider              | —              |
+| 输入框+按钮    | InputGroup          | F2,F3          |
+
+### 6.3 提交交互
+
+| 操作      | 触发                 | 前置条件     | 二次确认         | 目标页面/组件             | 返回行为                                                       |
+| --------- | -------------------- | ------------ | ---------------- | ------------------------- | -------------------------------------------------------------- |
+| 保存/提交 | 点击"确定"按钮       | 本地校验通过 | 否               | 校验 → 提交 → 成功        | 新建返回列表, 编辑返回原页, Sonner "保存成功"(C9)              |
+| 保存失败  | 提交返回错误         | —            | —                | —                         | 字段标红(F6) + Sonner 错误(C9), 留在表单页，聚焦第一个错误字段 |
+| 取消      | 点击"取消"按钮       | 有未保存内容 | 是 (Dialog 确认) | Dialog 确认(有未保存内容) | 确认后离开, 无未保存内容直接离开                               |
+| 返回      | 点击 Breadcrumb 返回 | 有未保存内容 | 是 (Dialog 确认) | 返回 ListPage             | 保持筛选+分页状态                                              |
+
+### 异步提交处理
+
+| 场景           | 提交后行为            | 反馈方式                                                         |
+| -------------- | --------------------- | ---------------------------------------------------------------- |
+| 同步提交(快速) | 阻塞 UI, 显示 Spinner | SubmitBar 按钮 disabled + `<Spinner data-icon="inline-start" />` |
+| 异步提交(耗时) | 不阻塞 UI, 后台处理   | Sonner "提交成功, 后台处理中" + 轮询状态                         |
+
+### 操作确认规范
+
+> 三级确认定义见 `rules/page-flow.json` operationConfirmationLevels。
+
+| 确认级别            | 适用操作                  |
+| ------------------- | ------------------------- |
+| 一级 (可逆)         | 保存/提交(本地校验通过时) |
+| 二级 (有未保存内容) | 取消/离开                 |
+
+### 6.4 @teamix-evo/ui 关键交互约定
+
+- **表单布局**: 用 `FieldGroup` + `Field`，不用 `div` + `space-y-*`(F1)
+- **字段校验**: `data-invalid` 在 `Field` 上，`aria-invalid` 在控件上(F6)
+- **禁用状态**: `data-disabled` 在 `Field` 上，`disabled` 在控件上(F6)
+- **2-5 选项**: 用 `ToggleGroup`，不用循环 `Button` 手动 active 状态(F4)
+- **相关选项组**: 用 `FieldSet` + `FieldLegend`(F5)
+- **InputGroup**: 内部用 `InputGroupInput`/`InputGroupTextarea`，不用原始 `Input`(F2)
+- **按钮在 input 内**: 用 `InputGroup` + `InputGroupAddon`(F3)
+- **Sonner 反馈**: `import { toast } from "sonner"`(C9)
+
+### 6.5 与 PageContainer 模式对照
+
+> 布局模式定义见 `rules/layout-rules.json`
+
+表单页使用 **模式 A（直接内容）或模式 B（Card 分组）**：
 
----
+```
+模式A: PageContainer → ContentWrapper → Breadcrumb + PageHeader + FieldGroup + SubmitBar
+模式B: PageContainer → ContentWrapper → Breadcrumb + PageHeader + Card[FieldGroup] + SubmitBar
+```
 
-## 7. 提交交互
+分区表单使用 **模式 B 扩展**：
 
-### 7.1 操作流
+```
+PageContainer → ContentWrapper → Breadcrumb + PageHeader + Card[FieldGroup] + Separator + Card[FieldGroup] + SubmitBar
+```
 
-| 操作             | 触发         | 前置         | 反馈                             |
-| ---------------- | ------------ | ------------ | -------------------------------- |
-| 保存             | 点[确定]     | 本地校验通过 | 校验 → 提交 → Toast「保存成功」  |
-| 保存失败         | 后端返回错误 | —            | 字段标红 + Toast 错误 + 留在表单 |
-| 取消（无未保存） | 点[取消]     | —            | 直接离开                         |
-| 取消（有未保存） | 点[取消]     | —            | Dialog 确认离开                  |
-| 返回（面包屑）   | 点击父级     | 有未保存内容 | Dialog 确认                      |
+## 规范引用
 
-### 7.2 异步提交
+- **读取路径**：见根技能 `../../SKILL.md` §4.5 三阶段读取决策树
+  - 阶段 ①：`page-types.json` + `business-mapping.json`
+  - 阶段 ②：`page-frame.json` + `layout-rules.json` + `page-flow.json`
+  - 阶段 ③（生成 HTML 时）：`design-tokens.json` + `design-tokens.css` + `styling.json` + `../boundaries.md` + `../foundations.md`（表单布局精确规格见本文 §8）
 
-| 类型         | UI                      | 反馈                                |
-| ------------ | ----------------------- | ----------------------------------- |
-| 同步（快速） | 按钮 disabled + Spinner | Toast 结果                          |
-| 异步（耗时） | 不阻塞                  | Toast「提交成功，后台处理中」+ 轮询 |
+> `rules/design-tokens.css` 是设计 Token 的唯一真相源（:root 变量定义）：生成 HTML 原型时需将 :root 变量块嵌入页面 `<style>` 标签；生成 React/TSX 需确保项目已通过 `@import` 引入该 CSS 文件。
 
-### 7.3 操作确认分级
+## 7. 验证清单 (Validation Checklist)
 
-| 级别             | 适用             |
-| ---------------- | ---------------- |
-| 一级（可逆）     | 保存（校验通过） |
-| 二级（有未保存） | 取消/离开        |
+> **通用检查项**（布局分区/颜色 Token/间距/字体/尺寸/禁用样式/异步操作/空数据/加载中）见根技能 `../../docs/validation-workflow.md` 验证清单。此处仅列出表单页特有检查项。
 
----
+| 检查项       | 检查点                                                                            | 目标       |
+| ------------ | --------------------------------------------------------------------------------- | ---------- |
+| 必需组件     | PageHeader、Form(FieldGroup)、SubmitBar                                           | 100%       |
+| 嵌套约束     | PageContainer → ContentWrapper → Breadcrumb + PageHeader + FieldGroup + SubmitBar | 无违规嵌套 |
+| 禁止组件     | 无 DataTable、Chart、内联 Input(不在 Field 内)、原始 div 布局                     | 0 个       |
+| 表单布局     | 所有 Input 在 Field → FieldGroup 内(F1)                                           | 正确       |
+| 字段校验     | 必填为空/格式错误/后端校验, data-invalid 正确                                     | 全部正确   |
+| 控件选型     | 每种字段场景使用正确 @teamix-evo/ui 组件                                          | 正确       |
+| 提交交互     | 前置条件、确认方式、异步处理                                                      | 正确       |
+| 取消确认     | 未保存内容时 Dialog 确认                                                          | 正确       |
+| 按钮 loading | SubmitBar 按钮 disabled + Spinner(C4)                                             | 正确       |
+| 分区表单     | Card 分组、Separator 分隔                                                         | 正确       |
 
-## 8. shadcn 表单组合契约
+## 8. 表单布局精确规格
 
-> 表单**组合层面**的本地约定。视觉/全局规则参见 [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)。
+> 来源：合并自原 `rules/forms.json` formLayoutSpecs / formComponentHeights / fieldOrientation。
+> 这是 horizontal 表单（左 label + 右控件，常见于设置页）的精确数值规范。Vertical 默认布局（label 在控件上方）使用 [foundations.md §3.5 表单专用三档间距](../foundations.md) 即可。
 
-- **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))
+### 8.1 字段方向 fieldOrientation
 
----
+| 取值               | 适用场景             | 描述                                                 |
+| ------------------ | -------------------- | ---------------------------------------------------- |
+| `vertical`（默认） | 新建/编辑表单        | label 在控件上方，自上而下排列                       |
+| `horizontal`       | 设置/详情类 settings | label 在控件左侧，`<Field orientation="horizontal">` |
 
-## 9. 嵌套约束
+### 8.2 form-row 布局规格（horizontal）
 
-| 父子关系                                                                          | 状态                        |
-| --------------------------------------------------------------------------------- | --------------------------- |
-| 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） |
+对应 [boundaries.md F7](../boundaries.md) 的精确数值规范。
 
----
+| 属性        | 值                              | CSS 变量         |
+| ----------- | ------------------------------- | ---------------- |
+| display     | `flex`                          | —                |
+| align-items | `center`                        | —                |
+| gap         | `24px`                          | `var(--gap-2xl)` |
+| padding     | `12px 0`                        | —                |
+| border-top  | 无（仅 Section 之间保留分割线） | —                |
 
-## 10. 禁止项
+```tsx
+<div className="form-row">
+  <FormLabel className="w-[140px] shrink-0">实例名称</FormLabel>
+  <div className="flex-1 min-w-0 max-w-[400px]">
+    <Input />
+  </div>
+</div>
+```
 
-| 禁项                        | 原因                          |
-| --------------------------- | ----------------------------- |
-| DataTable 在主内容区        | 关联数据用 Dialog + DataTable |
-| Chart 在表单页              | 图表属 Dashboard              |
-| 内联 Input（不在 Field 内） | 必须 FieldGroup → Field 包装  |
-| 原始 div 表单布局           | 用 FieldGroup + Field         |
-| 单页字段 > 15 不分组        | 分区或拆 Wizard               |
+### 8.3 form-label 规格（horizontal）
 
----
+| 属性        | 值                                                         | CSS 变量                    |
+| ----------- | ---------------------------------------------------------- | --------------------------- |
+| width       | `140px`                                                    | `var(--form-label-width)`   |
+| flex-shrink | `0`                                                        | —                           |
+| font-size   | `14px`                                                     | `var(--font-size-lg)`       |
+| font-weight | `500`                                                      | `var(--font-weight-medium)` |
+| color       | `hsl(var(--gray-primary))`                                 | —                           |
+| 垂直对齐    | 由 form-row `align-items: center` 控制，与所有控件中线对齐 | —                           |
 
-## 11. 表单页特有自检
+### 8.4 form-control 容器
 
-- [ ] PageHeader 用面包屑模式（L2 页面）
-- [ ] 所有 Input 在 Field → FieldGroup 内(FC1)
-- [ ] data-invalid + aria-invalid 双重声明(FC6)
-- [ ] 控件按字段类型选型正确（2~5 选用 ToggleGroup，不循环 Button）
-- [ ] SubmitBar 居右 + 按钮顺序：取消 → 上一步 → 主操作
-- [ ] 长表单（> 10）分组或分区
-- [ ] 异步提交：按钮 loading + Spinner
-- [ ] 取消时未保存内容 Dialog 确认
-- [ ] 编辑模式加载用 Skeleton
-- [ ] Toast 用 sonner（C9），不用自定义全局通知
+| 属性      | 值      |
+| --------- | ------- |
+| flex      | `1`     |
+| min-width | `0`     |
+| max-width | `400px` |
 
----
+### 8.5 form-description 辅助说明
 
-## 12. 《Teamix UI 表单设计规范》对齐 Checklist
+字段下方的辅助说明文本（用法提示、格式说明）：
 
-> 详细说明见 [`packages/ui/AGENTS.md` 第六节](../../../../ui/AGENTS.md#六表单族硬规则formfieldfilter-barlabelinput)。本节只列 AI 写表单时的 yes/no 自检项。
+| 属性        | 值                           | CSS 变量              |
+| ----------- | ---------------------------- | --------------------- |
+| font-size   | `13px`                       | `var(--font-size-sm)` |
+| color       | `hsl(var(--gray-secondary))` | —                     |
+| margin-top  | `4px`                        | —                     |
+| line-height | `1.5`                        | —                     |
 
-### 12.1 间距(11 条硬规则,§3.1)
+> Switch 横排布局例外：当 Switch 与描述文本同行（`display: flex; align-items: center; gap: 8px`），description 的 `margin-top` 设为 `0`。
 
-- [ ] 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 组件内置)
+### 8.6 form-footer SubmitBar 规格
 
-### 12.2 必填与 a11y(§一 + §六)
+表单页底部操作栏（行动点容器）：
 
-- [ ] `*` 后置:`<FormLabel required>` / `<FieldLabel required>`,**禁止**手写 `<span>* 邮箱</span>`
-- [ ] input 同步 `aria-required="true"`,纯视觉 `*` 不替代屏幕阅读
-- [ ] invalid 单一真值在 `<Field invalid>`,自动驱动 label 着色 + FieldError 可见 + 控件 ring,**不要**重复给控件传 `aria-invalid`
+| 属性       | 值                                                                  | CSS 变量        |
+| ---------- | ------------------------------------------------------------------- | --------------- |
+| 对齐       | `justify-content: flex-end`（所有行动点居右排列，禁止左右两端分布） | —               |
+| 按钮顺序   | 取消 → 上一步（如有）→ 下一步/提交                                  | —               |
+| height     | `72px`                                                              | —               |
+| gap        | —                                                                   | `var(--gap-sm)` |
+| border-top | `1px solid hsl(var(--gray-line))`                                   | —               |
+| background | `hsl(var(--card))`                                                  | —               |
 
-### 12.3 输入域宽度(5 档,§七)
+> 与 Dialog/Sheet Footer 的固定底部策略一致。CSS 模板见 §4 SubmitBar / Footer 定位规则。
 
-- [ ] 用 `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` 内置)
+### 8.7 表单组件高度统一规范
 
-### 12.4 响应式(5 档断点,§4.1-4.2)
+配置表单（单行排列）的主要输入类组件统一采用 **32px** 高度（`var(--input-height)`）以实现视觉对齐：
 
-- [ ] 多栏筛选用 `FilterBarPanel responsiveColumns={{ base, xs, s, m, l, xl }}`,**禁止**手写媒体查询 / `lg:grid-cols-*`
-- [ ] 单栏表单 < 432 自动改上下:`<Field orientation={{ base: 'vertical', xs: 'horizontal' }}>`
-- [ ] 断点用 `useBreakpoint` + `pickByBreakpoint`(`@/hooks/use-breakpoint`),**禁止**手写 `useMediaQuery`
+**统一 32px 的组件**：`Input` / `Select` / `Combobox` / `ToggleGroup`(`h-8`) / `InputGroup` / `Stepper`
 
-### 12.5 按钮容器感知(§六)
+**例外组件**：
 
-- [ ] 用 `FormActions container="page|page-stepper|modal|drawer"` 一次性配齐 position/align/alignWithInput
-- [ ] 决策口径:页面基础/分组 → `page` / 页面分步 → `page-stepper` / 弹窗 → `modal` / 抽屉 → `drawer`
-- [ ] **禁止**裸 `<div className="flex gap-2 justify-end">` 写底部按钮
+| 组件             | 尺寸             | 对齐方式                    | 用途                               |
+| ---------------- | ---------------- | --------------------------- | ---------------------------------- |
+| Switch           | 28×16px          | flex `align-items: center`  | 设置类场景开关                     |
+| Checkbox         | 16×16px          | flex `align-items: center`  | 表单复选框                         |
+| RadioGroup       | 16×16px          | flex `align-items: center`  | 单选组（相关选项用 FieldSet 包裹） |
+| Slider           | 4px（轨道）      | flex `align-items: center`  | 范围滑块                           |
+| Textarea         | auto（min 80px） | 独占一行                    | 多行输入，不与其他控件同行         |
+| SubmitBar Button | 36px             | 独立 Footer 容器（72px 高） | 不参与表单行 32px 对齐             |
 
-### 12.6 内容截断三件套(§八)
+**验证**：表单行内同行排列的 Input、Select、Combobox、Stepper 应视觉对齐（相同基线），无明显高度差异。
 
-- [ ] 横向宽度受限的字段值 / 长 label / 表格单元格用 `<Ellipsis>`,**禁止**手写 `truncate` + 独立 `<Tooltip>`
-- [ ] 多行截断走 `<Ellipsis lines={2}>`,**禁止**手写 `-webkit-line-clamp`
+### 8.8 字段必填/选填标识
 
-### 12.7 RHF vs Server Actions 流派(§6.1)
+> 这是 [boundaries.md FF4](../boundaries.md) 的精确数值规范。
 
-- [ ] 用 RHF + zod → 走 `Form / FormField / FormItem / FormLabel / FormMessage`(form 包,FormItem 内部就是 Field)
-- [ ] Server Actions / 原生 form / 简单状态 → 走 `Field / FieldGroup / FieldLabel / FieldError`(field 包)
-- [ ] **禁止**两套混用(Section / Actions 是 re-export 别名,选哪边都行,**不要交叉**)
+| 标识 | 实现                                                                                                               |
+| ---- | ------------------------------------------------------------------------------------------------------------------ |
+| 必填 | `<span className="required text-destructive">*</span>`，`font-size: 14px`，`margin-left: 2px`，紧跟 label 文字之后 |
+| 选填 | **不展示标识**（已移除"选填"文案）— 仅通过必填星号区分，未标星号即为选填                                           |