@tfdesign/b-end 1.0.4

package/skills/tfds/LAYOUT_RECIPES.md

@@ -0,0 +1,140 @@
+# TFDS 页面布局 Recipe（AI 先选 recipe，再写 JSX）
+
+> **作用域**：把页面模板、容器语义、间距、对齐和滚动模型压缩成 AI 可执行的布局决策表。生成整页时，先从本文件选择 **1 个主 recipe**，再读取 `components.index.json` 和 `LAYOUT_RULES.md` 写具体组件。
+>
+> **优先级**：组件索引 > `SKILL.md` > 本文件 > `LAYOUT_RULES.md` > `GLOBAL_DESIGN_RULES.md` > `DESIGN_PRINCIPLES.md`。本文件负责“先选哪种布局语义”，`LAYOUT_RULES.md` 负责更完整的骨架和响应式细节。
+
+---
+
+## 0. 生成前硬门禁
+
+每个整页文件生成前，先回答 4 个问题，并只选一个主 recipe：
+
+1. 用户进入页面后的第一步是什么？
+2. 页面主角是对象列表、AI 输入入口、消息流、主产物/编辑区，还是真人会话？
+3. 最外层内容应该直接坐浅灰底，还是进入白色工作卡？
+4. 谁负责滚动：整页、工作卡正文、表格、消息流，还是卡片网格？
+
+建议在草稿阶段保留一段 AI 自检注释，交付前可删除：
+
+```jsx
+// TFDS recipe: chat-home
+// container: gray-direct
+// scrollOwner: template-grid
+// cardColor: template cards white
+```
+
+---
+
+## 1. 五类页面主 Recipe
+
+| Recipe id | 触发场景 | 首选模板 | 背景 / 容器 | 典型组件 | 禁止项 |
+| --- | --- | --- | --- | --- | --- |
+| `base-management` | 筛选、搜索、浏览一批结构化对象、批量操作、查看详情 | `BasePageFramePattern` + 列表示例 | `main p-4 gap-2` 灰底框架 + 一张或多张白色 `WorkSurface` | `NavBar`、`FormTitle`、`FilterBar` 组合、`Table`、`TagBar`、`Tag` | 把页面 header 包白卡；`main p-2/px-6/px-8`；`max-w-* mx-auto` |
+| `chat-home` | 用户尚未进入上下文，第一步是输入需求 / 搜索助手 / 从模板开始 | `ChatHomePagePattern` | 右侧内容区直接保持 `var(--color-blueGrey-200)`，Hero / ChatInput / Tabs / 搜索 / 卡片网格直接坐灰底 | `NavBar`、`ChatInput`、`Tabs size="sm"`、`Input`、`Card color="white"` | 整块右侧首页内容外包 `bg-surface rounded-*`；模板卡用 `color="grey"` |
+| `chat-conversation` | 已在 AI 任务里持续追问、看执行流和产物 | `ChatConversationPattern` | 浅灰会话工作区，消息流和底部输入各自固定职责 | `ChatMessage`、`ChatInput`、`Button`、产物卡 | 用 `ChatBubble` 手搓 AI 消息；让底部输入随消息滚走 |
+| `copilot-workbench` | 对象 / 产物 / 编辑器是主角，AI 只是侧助 | `CopilotPagePattern` | 页面 header 直接坐灰底，主工作区进入白色 `WorkSurface`，AI 面板按辅助区处理 | `FormTitle`、`Tabs`、`ChatInput`、`TextArea/Input/Select`、产物区 | 做成纯聊天页；AI 侧栏抢主工作区宽度；整页滚动破坏对照 |
+| `im-thread` | 真人客服、私信、站内信、履约沟通 | `IMConversationPattern` | 会话背景按 IM 语义处理，线程列表 / 消息流 / 输入固定 | `ConversationList`、`ChatBubble`、`ChatInput variant="im-basic"` | 用 `ChatMessage` 渲染普通 IM；把推荐层塞到消息流和输入框之间 |
+
+---
+
+## 2. 容器语义表（不要只说“灰底 / 白卡”）
+
+| 容器类型 | 视觉定义 | 语义 | 允许子元素 | 禁止子元素 |
+| --- | --- | --- | --- | --- |
+| `AppShell` | `h-dvh w-full flex overflow-hidden` + `blueGrey-200` | 平台应用壳 | `NavBar`、右侧主内容区 | 白卡描边、整页圆角、`max-w-*` |
+| `PageMetaBar` | 直接坐灰底，无白卡背景 | 当前页面位置、标题、返回、页面级切换、主次操作 | `FormTitle variant="form"`、返回按钮、页面级 `Tabs`、操作按钮 | 表格、长表单、消息流、内容列表 |
+| `WorkSurface` | `color-surface` 白底 + `radius-lg` + 无 border / shadow | 用户真正做事的主工作区 | 表格、表单、编辑器、对话流、产物预览、参数区 | 页面级 header、面包屑、全局导航 |
+| `ContentCard` | 白底或灰底小卡，按父级背景决定 `Card color` | 重复项、模板项、指标项、结果项 | `Card`、`Tag`、少量 stats、入口箭头 | 承载整页主体、嵌套另一张大白卡 |
+| `InlinePanel` | 白卡内部的轻灰/弱描边分组 | 辅助分组、配置块、说明块 | 表单字段、参数组、轻提示 | 替代 `WorkSurface` 成为页面主容器 |
+| `MessageStream` | `flex-1 min-h-0 overflow-y-auto` | 时间线消息或 AI 执行流 | `ChatMessage` / `ChatBubble` | 表格主列表、筛选栏 |
+| `InputDock` | `shrink-0` 固定在工作流起点或底部 | 输入、发送、任务触发 | `ChatInput`、少量快捷按钮 | 随长内容一起滚动 |
+| `FloatingLayer` | 弹窗 / 抽屉组件自带白底、阴影和遮罩 | 临时任务、补充编辑 | `Modal`、`Sheet`、`FullScreenPage` | 手写 fixed div 弹窗 |
+
+---
+
+## 3. 间距 Recipe
+
+### 3.1 通用工作区
+
+| 层级 | 固定值 | 写法 | 说明 |
+| --- | --- | --- | --- |
+| 灰底框架到白卡 | 16px | `main p-4` | 页面外框间距，禁止 `p-2/px-6/px-8` |
+| 白卡之间 | 8px | `gap-2` | 并列 / 上下多白卡间距 |
+| 白卡内部 padding | 24px | `p-6` 或 `px-6 py-4 + px-6 pb-6` | 只用于白卡内部 |
+| 白卡内区块间 | 16px / 24px | `gap-4` / `gap-6` | 筛选区到表格默认 16px，较大 section 用 24px |
+| 同组控件 | 8px | `gap-2` | 按钮组、Tag 组、图标文字 |
+| 跨控件组合 | 12px | `gap-3` | 标题与状态、搜索与主筛选组 |
+
+### 3.2 AI 入口页
+
+| 区域 | 固定节奏 | 说明 |
+| --- | --- | --- |
+| Hero | `padding: 120px 40px 80px` | 只用于 `chat-home`，直接坐灰底 |
+| 主输入宽度 | `maxWidth: 680px` | `ChatInput` 居中，不再外包白卡 |
+| 筛选行 | `padding: 16px 40px` + `gap-4` | 左 Tabs、右搜索；空间不足允许换行 |
+| 搜索框 | `width: 240px`，`minWidth: 200px` | 固定宽，不撑满整行 |
+| 卡片网格 | `padding: 0 40px 40px` + `gap-4` | 网格自己滚动，卡片 `color="white"` |
+| 网格列宽 | `repeat(auto-fit, minmax(min(320px, 100%), 1fr))` | 禁止固定 3/4 列 |
+
+### 3.3 会话 / Copilot
+
+| 区域 | 写法 | 说明 |
+| --- | --- | --- |
+| 消息流 / 产物流 | `flex-1 min-h-0 overflow-y-auto` | 只让长内容滚 |
+| 底部输入 | `shrink-0` | 永远固定，不随消息滚 |
+| 面板头 | `shrink-0 px-6 py-4` | 标题和右侧操作固定 |
+| 面板正文 | `flex-1 min-h-0 overflow-hidden`，内部再分滚动层 | 保证输入、参数、结果可对照 |
+
+---
+
+## 4. 对齐 Recipe
+
+### 4.1 页面 Header / PageMetaBar
+
+- 左侧：`min-w-0 flex-1`，标题用 `<FormTitle variant="form" />`。
+- 右侧：`shrink-0 flex flex-wrap items-center justify-end gap-2`，只放 Button、页面级 Tabs、更多菜单。
+- 整行：`items-start justify-between gap-3`；空间不足时右侧操作换行，不压缩标题。
+- 禁止：`bg-surface rounded-*` 包住页面标题；禁止为了对齐内容卡而给 header 加白底。
+
+### 4.2 白卡 Header
+
+- 白卡主标题用 `<FormTitle variant="level-1" />`；白卡内 section 用 `level-2`。
+- 标题旁状态 / 数量 / 身份 Tag 放进 `titleSuffix`，不要放到右侧 action 区。
+- 右侧 action 区 `shrink-0 flex flex-wrap justify-end gap-2`。
+- 标题容器最小宽度不低于 120px，禁止标题一字一行。
+
+### 4.3 筛选栏 / 工具条
+
+- 搜索框固定约 240px；枚举 / 状态 / 时间控件 160-200px。
+- 筛选栏控件默认 36px 高；组内间距 8px，跨组 12px。
+- 多个筛选条件必须 `flex-wrap`，不要挤压标题或撑出页面。
+- 白卡内筛选栏靠近标题，标题到筛选默认 16px。
+- 禁止：在筛选栏把所有输入写成 `w-full`；禁止用 Button/Tag 冒充 Tabs。
+
+### 4.4 卡片网格
+
+- 网格使用 `auto-fit + minmax(min(Npx, 100%), 1fr)`，不要固定列数。
+- 模板 / 入口卡片：父级灰底，`Card color="white"`，网格 gap 16px。
+- 白卡内部的次级卡片：父级白底，`Card color="grey"` 或轻量 `InlinePanel`。
+- 每张卡标题、描述、Tag、stats 自然排布，禁止嵌套卡片。
+
+### 4.5 表格 / 列表
+
+- 白卡内部结构：标题区 `shrink-0` → 筛选区 `shrink-0` → 表格区 `flex-1 min-h-0 overflow-auto`。
+- 表格底部分页固定在表格容器内，不漂浮在白卡外。
+- 列表项主列文本可省略，但核心状态、错误原因、空状态说明必须完整可读。
+
+---
+
+## 5. AI 反例扫描
+
+生成完成后，按下面关键词自检：
+
+- `ChatInput` + 模板 `Card` 网格 + 外层 `bg-surface rounded`：入口页被大白卡包住，拆掉外层白卡。
+- `main` 上出现 `p-2` / `p-6` / `p-8` / `px-6` / `px-8`：外框间距错误，改 `p-4`。
+- `max-w-* mx-auto` 包住主工作区：页面被居中收窄，删除。
+- `Tabs size="md"` 出现在白卡、筛选区、卡片内、Playground 内：改 `size="sm"`，除非是平台顶部一级导航。
+- 筛选栏内 `Input className="w-full"`：大概率误用正文表单规则，改固定宽。
+- 背景为 `var(--color-surface)` 的最外层工作白卡同时有 `border` / `ring` / `shadow`：删除外层描边和阴影。
+- `<Card color="grey">` 出现在 `chat-home` 模板卡网格：改 `color="white"`。