# TFDS 常见失败模式与修复

> **作用域**：当生成页面“不像 TFDS”、组件看起来对但细节不对、或 IDE 不能稳定调用 `/产品设计-体服平台B端-界面生成` 时，先查本文件。

---

## 目录

- §1 `/产品设计-体服平台B端-界面生成` 没有真正加载规范
- §2 只读了设计原则，没有读组件详情
- §3 手写“看起来像”的组件
- §4 FormTitle 仍然是细体或伪标题
- §5 白卡被灰边框或阴影圈死
- §6 页面 header 被包进白卡
- §7 多面板页整页滚动
- §8 AI 入口页被大白卡包住
- §9 输入框在白卡正文里没有撑满
- §10 Tabs 被 Button 或 Tag 冒充
- §11 TextArea 代码字号偏大
- §12 Tailwind 没扫描包内组件
- §13 字重用了裸 `font-semibold` / `font-bold`
- §14 没有先选布局 Recipe，导致容器和间距混乱
- §15 头像用了随机外链或手写 img
- §16 ChatMessage 用户气泡在白底上仍是白色
- §17 Tabs / 筛选栏 / 按钮组横向溢出
- §18 结构容器被误加整卡 hover
- §19 密集内容用了弱对比或渐变背景

---

## 1. `/产品设计-体服平台B端-界面生成` 没有真正加载规范

**现象**：AI 说按 TFDS 做了，但仍在手搓组件、写 hex、用普通后台模板。

**原因**：当前对话没有加载 Skill，或 IDE 未重新扫描安装后的 Skill 目录。

**修复**：

- Cursor / Claude Code：重启 IDE 或重新打开项目后输入 `/产品设计-体服平台B端-界面生成`。
- Codex：新开/重启会话后输入 `/产品设计-体服平台B端-界面生成`；不出现时引用 `~/.codex/skills/产品设计-体服平台B端-界面生成/SKILL.md`。
- 其他 IDE：先读 `AI_READ_FIRST.md`，再按其中链路读取 Skill 文档。

---

## 2. 只读了设计原则，没有读组件详情

**现象**：页面气质接近，但 props、尺寸、交互和组件不一致。

**原因**：只读了 `DESIGN_PRINCIPLES.md` 或 `components.summary.json`，没有读取命中组件在 `components.index.json` 里的完整 rules。

**修复**：每个命中组件必须回查 `components.index.json#组件 id`。

---

## 3. 手写“看起来像”的组件

**现象**：Tag、Button、Tabs、FormTitle、ChatInput 看起来接近，但 hover、focus、字号、状态不一致。

**原因**：用 `div/span/button` 仿样式，而不是 import 组件。

**修复**：凡 `components.summary.json` 命中组件，必须整体 import：

```jsx
import { FormTitle, Tag, Button, Tabs } from '@tfdesign/b-end';
```

---

## 4. FormTitle 仍然是细体或伪标题

**现象**：标题左侧有竖条，但文字不是 600 字重，或仍是 `<h2>` / `<span>`。

**原因**：没有使用 `FormTitle`，或外部 className 覆写了组件字体。

**修复**：

- 页面、白卡、面板、section 标题全部用 `<FormTitle />`。
- 不传 `font-`*、`text-`* 覆写标题；字重以组件内 `[font-weight:var(--font-semibold)]` 为准（见 `GLOBAL_DESIGN_RULES.md` §2.2）。
- 状态数量用 `titleSuffix`。

---

## 5. 白卡被灰边框或阴影圈死

**现象**：页面看起来像旧式 admin，白卡边界很硬。

**原因**：最外层白卡加了 `border`、`outline`、`ring`、`shadow`。

**修复**：最外层工作白卡只保留：

```jsx
style={{ background: 'var(--color-surface)', borderRadius: 'var(--radius-lg)' }}
```

内部 Input / Select / Table / Tag 的描边保留。

---

## 6. 页面 header 被包进白卡

**现象**：顶部“标题 + 描述 + 操作按钮”是一张白卡，下方内容又是一张白卡，主从混乱。

**原因**：把页面元信息误当成工作区内容。

**修复**：页面 header 直接坐灰底；只有列表、表格、表单、对话、编辑器、运行结果进入白卡。

---

## 7. 多面板页整页滚动

**现象**：写 prompt、调参数、看结果需要上下滚，输入输出无法对照。

**原因**：Playground / 会话 / 编辑详情页误用了普通 Dashboard 滚动模型。

**修复**：整页 `overflow-hidden`，每个面板内部滚动；标题栏 `shrink-0`，正文 `flex-1 min-h-0 overflow-y-auto`。

---

## 8. AI 入口页被大白卡包住

**现象**：AI 入口首页外层是浅灰底，但右侧内容区又套了一整张很大的白色圆角卡，里面再放 `ChatInput` 和模板卡片，视觉变成“灰底 → 大白卡 → 卡片”。

**原因**：AI 把“白卡承载工作内容”泛化到入口页，把 Hero / 输入框 / 模板广场误判为结构化管理页工作区。

**修复**：

- 先确认页面是否是 `ChatHomePagePattern`：用户尚未进入上下文，第一步是输入需求 / 搜索助手 / 从模板开始。
- 若命中入口页，右侧主内容区保持 `var(--color-blueGrey-200)` 浅灰底。
- Hero、`ChatInput`、Tabs、搜索框、模板 Card 网格直接坐灰底。
- 删除包住整块首页内容的 `bg-surface rounded-*` / `background: var(--color-surface)` wrapper。
- 模板卡片自身使用 `<Card color="white" />`；只有列表管理、表单详情、表格、编辑器、多面板工作区才进入白色工作卡。

---

## 9. 输入框在白卡正文里没有撑满

**现象**：配置项、名称、标题输入框只占一小段，显得不专业。

**原因**：把筛选栏固定宽规则误用到正文表单。

**修复**：

- 筛选栏：固定宽。
- 白卡正文单列字段：`w-full`。

---

## 10. Tabs 被 Button 或 Tag 冒充

**现象**：一排按钮用于切换内容，状态和交互不像平台组件。

**原因**：没有区分“动作”和“视图切换”。

**修复**：

- 同一区域互斥内容切换必须用 `<Tabs />`（禁止用 Button/Tag 冒充）。
- 内容区（白卡/面板/表单分段/筛选维度/Playground）默认 **一律** `size="sm"`（省略 size 也等价）；只有平台顶部 header / 页面级顶导 / 产品级一级导航才允许 `md/lg`。
- 保持 Tabs 默认 `overflow="auto"`；窄容器中由 Tabs 内部横向滚动，不要用 `w-fit` / `min-w-max` 把父容器撑宽。

---

## 11. TextArea 代码字号偏大

**现象**：JSON / Prompt / 代码编辑区像放大版文本，行号和正文不稳。

**原因**：给 `TextArea variant="code"` 外部传了 `text-base` / `leading-6` 等覆写。

**修复**：直接使用组件默认 code variant，保持 14px / 20px。

---

## 12. Tailwind 没扫描包内组件

**现象**：组件样式缺失，黑边框、默认字体、颜色退化。

**原因**：缺少 theme.css 或 `@source`。

**修复**：

```css
@import "tailwindcss";
@import "@tfdesign/b-end/theme.css";

@source "./**/*.{js,jsx,ts,tsx}";
@source "../node_modules/@tfdesign/b-end/**/*.{js,jsx}";
```

## 13. 字重用了裸 `font-semibold` / `font-bold`

**现象**：标题或列表主文案「看起来加粗了」，但和预览 / Token 面板不一致，或在不同 Tailwind 版本下忽粗忽细。

**原因**：直接用 Tailwind 语义类 `font-semibold` / `font-bold`；在 Tailwind v4 下 `--font-`* 可能与 font-family 语义冲突。

**修复**：

- 需要 **600** 时写：`[font-weight:var(--font-semibold)]`（与 `FormTitle` / `Button` / `Form` 标签等一致）。
- 需要 **700** 且组件 rules 允许时写：`[font-weight:var(--font-bold)]`。
- 页面标题一律用 `<FormTitle />`，不要手写 `h2 + font-semibold`。

---

## 14. 没有先选布局 Recipe，导致容器和间距混乱

**现象**：页面看起来用了 TFDS 组件，但布局像拼贴：入口页被白卡包住、列表页左右留白过大、筛选栏控件不齐、卡片网格间距不统一、Tabs 尺寸忽大忽小。

**原因**：AI 直接从组件开始写 JSX，没有先判断页面属于 `base-management` / `chat-home` / `chat-conversation` / `copilot-workbench` / `im-thread` 哪个 recipe。

**修复**：

1. 回到 `PAGE_ARCHETYPES.md`，用“用户第一步动作”选模板。
2. 打开 `LAYOUT_RECIPES.md`，选择唯一主 recipe。
3. 按 recipe 决定容器：灰底直排、白色工作卡、会话流、Copilot 工作台或 IM 线程。
4. 再补组件：`FormTitle`、`Tabs`、`Input`、`Table`、`ChatInput`、`Card` 等。
5. 最后扫描反例：`main p-2/px-6`、`max-w-* mx-auto`、`bg-surface rounded` 包入口页、筛选栏 `w-full`、内容区 `Tabs size="md"`。

---

## 15. 头像用了随机外链或手写 img

**现象**：IM 对话、ChatBubble、Table 负责人列、NavBar 底部用户头像使用 `https://i.pravatar.cc`、Unsplash、placeholder 图片，或手写 `<img className="rounded-full">`。

**原因**：AI 把头像当成普通图片占位，没有读取 `Avatar` / `ChatBubble` / `Table` 的素材来源规则。

**修复**：

- 人像类头像必须用 `Avatar` / `AvatarGroup`，IM 气泡用 `ChatBubble`，表格头像列用 `Table type="avatar"` / `type="avatarText"`。
- 缺省头像不要传随机外链；`Avatar` 图片态未传 `src` 时会自动随机使用包内本地成员头像素材。
- 需要稳定绑定成员时，从包内导出的 `getTeamMemberByIndex` / `getTeamAvatarBySeed` 取本地成员头像，再传给 `avatarSrc`。

---

## 16. ChatMessage 用户气泡在白底上仍是白色

**现象**：白色大背景 / 白色工作卡内，`ChatMessage role="user"` 仍然是纯白气泡，气泡边界和父背景混在一起。

**原因**：旧规则要求手动传 `userBubbleTone="fill"`，AI 容易漏传；或直接写死 `userBubbleTone="surface"`，导致白底上仍使用白色气泡。

**修复**：

- 默认不传 `userBubbleTone`，让组件使用 `auto` 根据最近父级背景自动适配。
- 白色大背景 / 白色工作卡内应呈现灰色 `fill` 气泡；复杂白底无法识别时显式传 `userBubbleTone="fill"`。
- 浅灰、蓝灰、AI 会话灰底等非白背景应呈现白色 `surface` 气泡；只有复杂非白背景无法识别时才显式传 `userBubbleTone="surface"`。

---

## 17. Tabs / 筛选栏 / 按钮组横向溢出

**现象**：页面或卡片右侧出现被撑开的空白，Tabs 超出卡片边界，筛选控件或按钮组被裁切、挤出白卡，默认浏览器缩放下需要横向滚动整页。

**原因**：横向 flex 子项漏写 `min-w-0`，或给 Tabs / 筛选行 / 操作区写了 `w-fit`、`min-w-max`、固定大宽度、`overflow-visible`；也可能把所有筛选项强制塞进一行，未允许 wrap 或内部滚动。

**修复**：

- Tabs：直接使用 `<Tabs />` 默认 `overflow="auto"`；父级补 `min-w-0 max-w-full overflow-hidden`，不要覆写为 `w-fit` / `min-w-max`。
- 筛选栏：使用 `flex items-center flex-wrap gap-2`；搜索约 240px，筛选控件 160-200px，按钮 `shrink-0`。
- 表单 / 参数网格：使用 `grid-template-columns: repeat(auto-fit, minmax(min(100%, 240px), 1fr))` 或在窄面板降为单列。
- 操作按钮组：右侧 action 区 `shrink-0 flex flex-wrap justify-end gap-2`；超过可读宽度时收进更多菜单。
- 表格 / 代码 / 日志超宽时，只允许对应内容区 `overflow-auto`，禁止把整页撑宽。

---

## 18. 结构容器被误加整卡 hover

**现象**：主工作白卡、设置面板、结果面板、详情侧栏等结构容器 hover 时整块变白、加阴影或浮起，页面像入口卡片列表，工作区层级变乱。

**原因**：AI 把“可点击入口卡”的 hover 反馈套到了结构性工作容器上。

**修复**：

- 只有明确可点击的入口卡、列表项、选项卡片、推荐卡片可以做 hover fill / shadow / lift。
- 主工作白卡、表单面板、表格容器、代码结果面板、对话区、详情侧栏等结构容器不做整卡 hover。
- 结构容器内部的按钮、行、tab、选项可以保留各自 hover；反馈只发生在真正可交互的子元素上。

---

## 19. 密集内容用了弱对比或渐变背景

**现象**：表格、表单、日志、代码、JSON、配置项、运行结果放在透明、渐变、浅彩色背景上，文字和边界变虚，扫描效率下降。

**原因**：把 AI 语义面、推荐卡或装饰性背景误用于密集工作内容。

**修复**：

- 表格、表单、日志、配置、代码、结果、长文本编辑器必须使用稳定白底、`Card color="grey"` 或组件指定的代码 / 填充背景。
- AI 渐变只用于 AI 生成内容、推荐、诊断、洞察、AI 标识；不要用于用户可编辑输入区或普通业务数据区。
- 需要层级时先用 `FormTitle`、间距、行线、轻填充、组件边界，不要用大面积渐变或透明玻璃制造层级。
