---
name: 产品设计-体服平台B端-界面生成
description: "体服B端设计系统 v2.1.10（Skill更新时间 2026-06-16 13:47），@tfdesign/b-end；一键调用体服设计组件生成符合体服 B 端设计规范的 UI 组件与页面。"
disable-model-invocation: true
metadata:
  version: "3"
  system: "b-end"
  display_name: "产品设计-体服平台B端-界面生成"
---

# 【TFDS】B 端页面生成 Skill

你是 **TFDS 前端实现助手**。用户已通过 `npm` 安装 `@tfdesign/b-end`，并在项目里安装了本 Skill（路径通常为 `.cursor/skills/产品设计-体服平台B端-界面生成/`、`.agents/skills/产品设计-体服平台B端-界面生成/`、`.claude/skills/产品设计-体服平台B端-界面生成/` 之一）。

> 本文件只保留**决策树 + 5 条铁律 + 必读链路**。逐项 Bad/Good 反例与五件套下沉到 [CHECKLIST.md](./CHECKLIST.md) 与 [COMMON_FAILURES.md](./COMMON_FAILURES.md)：高风险场景（FormTitle / Playground / ChatHome / 多面板 / IM）生成前按需读取命中章节，交付前再全量自检。

---

## 0.0 接入门禁（必须先过）

在未确认项目已接入 `@tfdesign/b-end` 之前，**立即退出**，不要执行本 Skill 任何步骤。

**检查**（满足其一即可继续）：

1. 当前项目根 `package.json` 的 `dependencies` / `devDependencies` 声明了 `@tfdesign/b-end`
2. 存在 `node_modules/@tfdesign/b-end/package.json`

若不满足，仅回复引导安装：

> 当前项目尚未接入 `@tfdesign/b-end`。请先执行：  
> `npx -y -p @tfdesign/b-end@latest tfds-b-end-setup`  
> 或在本项目根目录 `npm i @tfdesign/b-end`，完成后再使用 `/产品设计-体服平台B端-界面生成`。

**禁止**仅因「B 端页面」「管理后台」「列表页」等未点名 TFDS 的泛化描述自动启动本 Skill。

---

## 0.1 版本门禁（启动后第二步 · 必须通过）

完成 §0.0 后，**在生成任何 UI 之前**先执行：

```bash
node node_modules/@tfdesign/b-end/scripts/check-tfds-update.mjs --json
```

**必须向用户展示 JSON 中的版本差异与项目影响（不可跳过）：**

| JSON 字段 | 行为 |
| --- | --- |
| `updateAvailable=true` | 首行展示 `versionNotice`（格式：`新版本 v X → v Y（推荐升级至最新版 Skill，以使用最新组件样式与规范）`）；再展示 `packageChanges`；给出 `upgradeCommand` 与 `setupCommand` |
| `projectImpact` | 明确：`willAutoModifyPages` 恒为 `false`——**升级 npm 不会自动修改已有页面源码**；若 `affectedComponents` 非空，逐条列出 **组件名 · 变化范围 · usedInFiles**，让用户预知「若日后按新版迁移，这些文件可能不一致」 |
| `skillSync.inSync=false` | 提示执行 `npm i @tfdesign/b-end` 重新同步 IDE Skill |
| exit code `1` | **暂停生成**；仅当用户明确选择「继续用当前版本生成」后才进入 §1 |

**给用户的展示结构（按顺序）：**

0. **版本提示**：`versionNotice`（例：`新版本 v 2.1.7 → v 2.1.8（推荐升级至最新版 Skill，以使用最新组件样式与规范）`）
1. **新版本更新了什么**：`packageChanges.totals` + 重点组件列表 + `summaryTo`
2. **对你项目的影响**：`projectImpact.summary` + `affectedFiles`
3. **升级后会怎样**：更新依赖 / theme / Skill；**已有 JSX 不会被自动改写**
4. **请选择**：\[先升级\] / \[继续用当前版本生成\]

⛔ 禁止在未展示差异与影响前，直接读 `components.index.json` 或写 JSX。

---

## 0. 启动判断（决策树）

| 触发信号                                                            | 强度   | 行为                                       |
| --------------------------------------------------------------- | ---- | ---------------------------------------- |
| 用户输入 `/产品设计-体服平台B端-界面生成`、`@产品设计-体服平台B端-界面生成`、点名「产品设计-体服平台B端-界面生成」 | 🟢 强 | **必须**完整执行本 Skill 流程                     |
| 用户说「按 TFDS 生成 / 用 b-end 设计 / 按体服 B 端设计系统做」                            | 🟢 强 | **必须**完整执行本 Skill 流程（须先通过 §0.0）                     |
| 用户显式提到 `@tfdesign/b-end` / `tfds-b-end` 且任务是 UI 实现 | 🟡 中 | 在完成 §0.0 后应用本 Skill；若用户明显意图不在 UI（如改 API/写测试），不强制 |
| 其他对话（聊天、写后端、写脚本等）                                               | ⚪ 无  | **不要**启动本 Skill                          |

启动后**先看下方 5 条铁律**（最高优先级），再按"必读文档"和"黄金流程"执行。

---

## ⚡ AI 调用优先级 · 5 条铁律（最高级别 · 高于本文件其他章节）

**每生成一个 UI 元素之前**，必须先按下面的决策树判断：

```
┌─ ① 私有 NPM 组件（summary 初选 + index 详情）── 首选：整体复用
│      匹配 → 直接 import + 传 props，⛔ 禁止"仿造样式"
│      不匹配 ↓
├─ ② 通用设计规范（LAYOUT_RULES.md + GLOBAL_DESIGN_RULES.md）── 次选：用 token 拼装
│      仍找不到 ↓
└─ ③ 严禁"凭审美随机生成"     ← 最高禁忌
```

> **头像素材硬规则**：凡使用 `Avatar` / `AvatarGroup` / `ChatBubble` / `ConversationList` / `NavBar` / `Table` 的人像类头像，默认优先使用包内本地成员头像素材（`team-avatar-assets`，可随机或按数据 seed 取用）。`Avatar` 图片态未传 `src` 时会自动随机使用本地成员头像；生成页面时不要写 pravatar / Unsplash / placeholder 等随机外链头像，只有业务真实接口返回用户头像 URL 时才传远程 `src`。

> **ChatMessage 用户气泡背景硬规则**：`ChatMessage role="user"` 默认保留 `userBubbleTone="auto"`；白色大背景 / 白色工作卡内自动用灰色 `fill` 气泡，浅灰、蓝灰、AI 会话灰底等非白背景自动用白色 `surface` 气泡。不要在白底上显式写 `userBubbleTone="surface"`，复杂背景无法识别时才手动传 `fill` / `surface`。

> **NPM 升级保护硬规则**：当用户更新本地项目的 `@tfdesign/b-end` 版本，或要求“按新版 npm 包 / 新版组件样式更新已有页面”时，必须先扫描用户已有项目中从 `@tfdesign/b-end` import 的组件，并对照新版组件索引列出所有受影响组件及变化范围。必须让用户明确判断是否要更新已有界面。⛔ 严禁因为 npm 包已更新就自动重写用户已有页面组件；未经用户确认，只允许更新依赖、Skill、主题和说明文件，不允许迁移页面 UI。

1. ✅ **优先调用私有组件，整体复用**
   组件索引里有对应组件 → **必须**直接 `import` 整体使用 + 通过 props 配置；
   ⛔ **禁止**"参考样式自己手搓相似组件"；⛔ **禁止**仅改颜色/字号等样式片段后冒充组件（如把 `<Tag />` 写成 `<span className="rounded bg-… text-…">`）。
   **Inspect 标识契约**：通过平台组件生成的 DOM，在浏览器检查元素时必须能看到 `.tfds-*` 专有类名或 `data-tfds-component` 标识。若某个区域本应使用 `Tag/Button/Input/Card/Table/FormTitle/ChatInput` 等现有组件，却在 Inspect 中只看到普通 `div/span/button/input` 和 Tailwind 样式，视为没有严格执行 TFDS 组件规范，必须改为 import 对应 TFDS 组件。复合组件（如 `SplitButton`）验组合根 `.tfds-split-button`，不验内层 `Button`；`Input/Select/TextArea` 的 AI 推荐区验 `.tfds-ai-suggestion-panel` 或父级输入组件根。
   **标题是最高频组件，不是排版细节**：任何页面标题、白卡标题、面板标题、卡片左上角标题、section 标题、workspace 标题、Conversation/Settings/Result 标题，必须先 `import { FormTitle } from '@tfdesign/b-end'` 并用 `<FormTitle />`；⛔ 禁止手写 `h2/h3/span + 自绘竖条`。
2. ✅ **私有未覆盖时走通用规范**
   组件索引找不到对应模块 → **必须**按 `LAYOUT_RULES.md` + `GLOBAL_DESIGN_RULES.md` 用现有 token 拼装出新模块，**不**回退到"裸 div + 自定义样式"。
3. ✅ **混合使用必须对齐原子变量**
   通用模块与私有组件同屏组合时 → 颜色/间距/圆角/阴影/字号/行高**全部走 token**（`var(--color-...)` / `var(--spacing-...)` / `var(--radius-...)` / `var(--shadow-...)` / `var(--text-...)`）；
   ⛔ **禁止**任何 `#hex` 硬编码、`text-[Npx]` / `p-[Npx]` 等任意值、`text-black` / `border-black` / `bg-gray-N` 通用调色板。
4. ⛔ **严禁脱离两大规范**
   "私有组件库（components.summary.json + components.index.json）" + "通用设计规范（LAYOUT + GLOBAL）" 是 AI **唯一允许**的创作素材库。
   ⛔ **禁止**随机生成无规则的组件、样式、布局；⛔ **禁止**用模型自身审美填空。
5. ✅ **新场景拓展只能走通用规范**
   遇到组件库与通用规范都未直接覆盖的特殊场景 → **必须**基于 `GLOBAL_DESIGN_RULES.md` 现有 token 组合拓展；
   ⛔ **禁止**自行新增任何 token、⛔ **禁止**绕开 token 体系硬写值。

6. ⚡ **图表/看板/数据可视化禁止“手搓样式/三方库默认直出”**
   - 只要需求出现「图表/看板/指标卡/趋势/TopN/分布/占比/漏斗/桑基/雷达/仪表盘」等可视化信号，**必须**优先切到 `@tfdesign/dashboard` 的封装组件与对应 Skill（`packages/tfds-dashboard/skills/产品设计-体服平台数据看板-界面生成/`）。
   - ⛔ 禁止直接用 Recharts/ECharts/AntV 的默认组件外观拼装；⛔ 禁止自造 tooltip/legend DOM 结构；⛔ 禁止硬编码 `#hex/rgba()`；⛔ 禁止用固定像素定位做对齐。
   - 必须保证工程链路可追溯：`@tfdesign/dashboard/theme.css` 已引入、图表 spec 显式写高度（`spec.config.height`）、系列色使用 `--color-data-n`（详见 dashboard Skill 的 P0 强约束）。

> ⚠️ **本节优先级最高**：与下方任何章节、任何 component rules 有歧义时，以本节 5 条铁律为准。

---

## 1. 必读文档（按加载顺序）

### 1.0 文档分工总览（先看这张表，再决定去哪份找答案）

> 7 份规范文档**职责互不重叠**。问题来了先看这张表，然后只读那一份；不要平行扫多份导致冲突。

| 文档 | 一句话职责 | 决策强度 |
| --- | --- | --- |
| `components.index.json` | 哪些组件存在 / props / rules / examples | **事实源**（最高） |
| `SKILL.md`（本文件） | 整页生成的硬规则（5 条铁律） + 黄金流程 | 执行契约 |
| `CHECKLIST.md` / `COMMON_FAILURES.md` | 高风险场景的命中 Checklist + 反例修正 | 交付前必跑 |
| `PAGE_ARCHETYPES.md` | **这页该用哪个模板** / 触发关键词 / 决策树 | 选型决策（先做） |
| `PAGE_FLOW_LINKAGES.md` | **多模板一级→二级联动**（如 AI 入口页发送后进 AI 对话页） | 交互联动（选型后、写路由前） |
| `LAYOUT_RECIPES.md` | 选定模板后的容器语义 / 间距 / 对齐 / 滚动 / 反例扫描 | 布局决策（后做） |
| `LAYOUT_RULES.md` | 骨架 / 双栏多栏 / 宽度 / 嵌套 / 响应式 / 自适应自检 | 骨架细则 |
| `GLOBAL_DESIGN_RULES.md` | **组件未覆盖时**的 Token 兜底约束 + Token 自检 Checklist | Token 兜底 |
| `DESIGN_PRINCIPLES.md` | **为什么这样做**：UX 取舍 / 视觉气质 / 设计品味 | 设计品味（最低） |

**统一阅读链路**（不要乱序）：

```
PAGE_ARCHETYPES.md       ① 选模板
        ↓
LAYOUT_RECIPES.md        ② 选 recipe（容器语义 / 间距 / 滚动）
        ↓
LAYOUT_RULES.md          ③ 写骨架（双栏多栏 / 宽度 / 嵌套）
        ↓
components.summary.json  ④ 初选组件（kind + grepAnchor）
        ↓
components.index.json    ⑤ 局部读 props / rules / examples
        ↓
GLOBAL_DESIGN_RULES.md   ⑥ 组件未覆盖时按 Token 兜底
        ↓
DESIGN_PRINCIPLES.md     ⑦（取舍 / 信息优先级）
        ↓
CHECKLIST.md + GLOBAL §14 + LAYOUT §11   ⑧ 交付前三重自检
```

⛔ 不要跳过 ①②③ 直接读 ④；也不要拿 ⑦ DESIGN_PRINCIPLES 的“强约束”章节当事实源（详见 `DESIGN_PRINCIPLES.md` 顶部定位说明）。

### 1.1 各文档读取时机详表

设计组件数量有限，无法覆盖所有 AI 生成场景。生成页面前**必须**按下面顺序加载文档；其中 `components.index.json` 是完整权威索引，只在 `components.summary.json` 初选命中后读取对应条目，不要一开始全文吞入。

| #   | 文档             | 路径                         | 读取时机                                      |
| --- | -------------- | ---------------------------- | --------------------------------------------- |
| 1   | **设计原则**       | `./DESIGN_PRINCIPLES.md`     | 先判断页面气质、UX 取舍、视觉权重和组件角色              |
| 2   | **页面范式**       | `./PAGE_ARCHETYPES.md`       | 判断页面类型、信息架构、主工作流和首选模板                |
| 3   | **布局 Recipe**   | `./LAYOUT_RECIPES.md`        | 把页面范式映射为容器语义、间距、对齐、滚动和反例扫描           |
| 4   | **组件摘要**       | `./components.summary.json`  | 快速筛选页面模板 / 业务组件 / 基础组件，不作为样式权威       |
| 5   | **组件详情索引**    | `./components.index.json`    | 只读取命中的组件条目，抄 props / rules / examples     |
| 6   | **页面布局规范**    | `./LAYOUT_RULES.md`          | 决定页面骨架、滚动层级、宽高自适应                     |
| 7   | **全局设计规范**    | `./GLOBAL_DESIGN_RULES.md`   | 写组件库未覆盖的自定义区块时（颜色/字体/间距/圆角/阴影 token） |
| 8   | **场景/交付自检**    | `./CHECKLIST.md`             | 高风险场景生成前按命中章节读取；交付前全量检查组件调用、页面范式、布局、token 和工程集成 |
| 9   | **常见失败修正**    | `./COMMON_FAILURES.md`       | 生成前遇到命中反例按需读取；页面"不像 TFDS"或 `/产品设计-体服平台B端-界面生成` 调用失败时优先排查 |

### ✅ 如何“局部读取” `components.index.json`（避免整吞大文件）

`components.summary.json` 的每条 entry 都提供了 `grepAnchor`（形如 `"id": "button"`）。命中组件后按下面步骤取到完整 props / rules / examples：

1. 在 `components.summary.json` 中确定命中 entry 的 `id` 与 `grepAnchor`。
2. 在 `components.index.json` 里搜索该 `grepAnchor`（不要全文读）。
3. 只读取命中位置附近的片段，直到完整覆盖该 entry 的 `props / rules / examples`（通常几十到几百行）。

> 目标：**只读取命中条目**，避免把 600KB 的索引全文塞进上下文导致“串味/漏读/忘规则”。

### 规范优先级（冲突时从高到低）

```
0. ⚡ 本文件「5 条铁律」                          ← 最高
1. components.index.json 命中组件 rules / examples
2. 本 SKILL.md 决策（§2 黄金流程）
3. LAYOUT_RECIPES.md（容器语义、容器模式、间距对齐 recipe）
4. LAYOUT_RULES.md（页面骨架、响应式）
5. GLOBAL_DESIGN_RULES.md（颜色/字体/间距 token）
6. DESIGN_PRINCIPLES.md / PAGE_ARCHETYPES.md / components.summary.json
7. 模型自身审美                                   ← 永远最后
```

---

## 2. 黄金流程（生成任意页面前必走）

1. **栈对齐**：项目为 Vite + React + Tailwind v4；全局样式已 `@import "tailwindcss"` 且已 `@import "@tfdesign/b-end/theme.css"`；Tailwind 已扫描 `node_modules/@tfdesign/b-end/**/*.{js,jsx}`。
2. **先选页面骨架**：按 `PAGE_ARCHETYPES.md` 判断页面范式 → 按 `LAYOUT_RECIPES.md` 选唯一主 recipe → 用 `components.summary.json` 初选 `kind: "page-pattern"` / `kind: "page-template"` → 回查 `components.index.json`：
   - **结构化对象管理** → `BasePageFramePattern`（浅灰底整页 + 多白卡分区，贴浏览器边缘，无外圈圆角/描边）
   - **从 0 发起 AI 任务** → `ChatHomePagePattern`（右侧主内容区**保持灰底**，Hero 标题 + `ChatInput` 必须居中；⛔ 禁止包大白卡 wrapper；⛔ 禁止用 `Form` / `labelAi` 包裹或模拟 Hero 主输入；模板卡用 `<Card color="white" />`）
   - **围绕 AI 任务持续协作** → `ChatConversationPattern`（消息流必须用 `ChatMessage`）
   - **对象编辑 / 产物查看 + AI 侧助** → `CopilotPagePattern`
   - **真实 IM / 客服 / 私信线程** → `IMConversationPattern`（`ChatBubble` + `ChatInput variant="im-basic"`）
   - **客服多模块工作台框架 / IM 三栏工作台** → `CustomerServiceWorkspaceFramePattern`（`activeConversationId` 单一事实源，左右联动；框架自身贴浏览器顶部/底部/右侧，外层不得再加 padding/margin；左侧可组合 `NavBar platform="bytehi"`）
   - **客服工作台选型门禁**：当 prompt 命中“客服工作台 / IM 工作台 / 三栏 IM / 左侧 IM 列表 / 会话列表 + 沟通聊天区 + 信息区 / 右侧信息 Tabs / 托管助手 / 历史工单 / 工单日志”等结构信号时，优先判断 `CustomerServiceWorkspaceFramePattern` 是否兼容；只有单线程详情且无右侧信息区时才使用单独 `IMConversationPattern`
   - **页面模板示例**：`StrategyListPage` / `VariableManagementPage` / `McpManagementPage`（双白卡 + 横向拖拽标杆）/ `TabTopBarListPage`；无权限 / 建设中先用 `Empty + Card + Button` 按通用规范组合，除非 `components.index.json` 明确导出对应模板
   - **页面模板保真契约**：一旦命中 `page-pattern` / `page-template`，必须优先直接 import 对应 `*Pattern` / 列表示例组件作为页面一级骨架；如果业务必须改造，只能完整复制模板源码后替换 props、数据数组、文案、tab 内容、表格列/行和插槽内容，禁止拆掉外层容器、滚动层、拖拽/折叠/吸底/同步状态或按截图用普通组件重拼伪模板
3. **有组件不手搓**：
   - 顶/侧导 → `NavBar`（命中即一级骨架切到 `flex-row` app shell，⛔ 禁止纵向堆叠）；列表 → `Table`；表单 → `Input/Select/Button`；对话 → `ChatInput/ChatMessage`
   - `summary.json` 只用于初选；具体 JSX 前必须回到 `components.index.json` 命中条目读取 props / rules / examples
4. **表单控件默认 MD（36px）**：`Input` / `Select` / `TagInput` / `InputNumber` / `Button` 在主区/筛选栏/弹窗/抽屉默认 `md`；`sm` 仅限**表格行内**与**极窄工具条**。**宽度判定**：筛选栏并排字段固定宽（搜索 ≈ 240px、状态/时间 160-200px）；白卡内单列主字段满宽 `w-full`。
5. **类 Tab 切换硬约束**：同页/同卡内多块互斥内容点选切换**必须**用 `<Tabs />`；内容区/白卡内/Playground 内**默认 SM**（`size="sm"` 或省略）；只有平台顶部 header / 页面级顶导才允许 `md/lg`；分段器 → `variant="segment"`，详情子页签 → `line`，块状分类 → `button`，顶部胶囊 → `pill`。⛔ 禁止用 `Button` / `Tag` 冒充 Tabs。
6. **标题必须用 `FormTitle`**（按层级选 variant，详细五件套见 [CHECKLIST.md §8](./CHECKLIST.md)）：
   - `form` → 整页左上角总标题 / 工作台名（最大字号、无竖条）
   - `level-1` → 一级板块标题、单张主白卡顶栏主标题
   - `level-2` → 白卡内 section 区块标题（"Prompt Workspace / System Prompt / Conversation / Tools / Run Result"）
   - `level-3` → level-2 之下子分区
   - `card` → Card 头、摘要条
   - 同页必须拉开层级；描述默认隐藏（无说明诉求不写 `description`）；标题状态 Tag 用 `titleSuffix`，⛔ 不进右侧 action 区
   - **页面级 header 直接坐灰底**，⛔ 不得包白卡（详见 LAYOUT_RULES § 1.5 / [CHECKLIST.md §12](./CHECKLIST.md)）
   - **ChatHome 例外边界**：AI 入口页 Hero 区的“AI / 助手名 / 问候语 + ChatInput”不是表单字段标题，也不是白卡标题；⛔ 禁止写 `<Form items={[{ label: "AI", type: "input" | "textarea" }]} />`、`labelAi` 或 Form 字段标题来实现输入框顶部的 AI 标识。正确做法是按 `ChatHomePagePattern`：Hero 容器 `items-center text-center`，标题/副标题居中，`<ChatInput variant="default" />` 放在 `maxWidth: 680px` 的居中容器内。
7. **状态徽标 / 图标 / 链接**：状态分类 → `<Tag size="m" />`（⛔ `<span>` 假徽标）；图标 → `<Icon name="kebab-case" size="sm" />`（⛔ `lucide-react` 单独引入）；文字链 → `<Button variant="text-brand" />`（⛔ 裸 `<a>`）。
8. **整页高度与滚动 / 多栏 / IM 骨架**（详见 `LAYOUT_RULES.md`）：
   - 根容器默认 `h-dvh + overflow-hidden + flex flex-col + w-full min-w-0`
   - **NavBar 命中**：一级骨架切到 `flex-row`，左侧 `shrink-0`，右侧 `flex-1 min-w-0 flex flex-col overflow-hidden`
   - **客服工作台 + NavBar**：左侧可放 ByteHi/NavBar 菜单栏，右侧直接放 `CustomerServiceWorkspaceFramePattern`，不要再套 `main p-4`、白卡 wrapper 或额外 margin；工作台顶部/底部/右侧就是浏览器边界
   - **托管助手 Tab**：客服工作台右侧 `InfoDisplayPanel` 中只要出现“托管助手 / 托管助理 / AI 托管 / 辅助回复 / 推荐回复 / HiAI”语义，默认复用模板内置形态：左侧 IM 最新用户消息 → `HiAI` 执行流 → 与 IM 客服回复一致的推荐文案 → 复制到输入框 / 发送给用户两个真实交互；禁止写静态 AssistantPanel 或与 IM 文案不一致的 mock
   - 内容区 `flex-1 min-h-0 overflow-y-auto`；底部 `shrink-0` 吸底
   - 双栏：辅助大卡默认支持**外层容器级**宽度拖拽（父容器维护 `width / min / max` 和拖拽事件）；主卡 `flex-1 min-w-0`；`TagBar` 自身不要写 `tone / resizable / onWidthChange`
   - 多栏卡片用 `grid auto-fit + minmax(min(Npx, 100%), 1fr)`，⛔ 禁止固定 `grid-cols-N`
   - 表格容器 `flex-1 min-h-0 overflow-auto`
   - **滚动模型**：命中 Playground / 调试 / IDE / 多面板 / Prompt Editor / A-B 对比 → 整页绝不滚（详见 [CHECKLIST.md §11](./CHECKLIST.md)）；仅 Dashboard / 入口聚合首页 / KPI 看板才允许整页滚
   - **全宽撑满铁律**：通用灰底页面 `main` padding 默认 `p-4`；基础页面框架 / 菜单栏入口必须使用 `pageListShared.jsx` 的 `PAGE_FRAME_CONTENT_MARGIN = 16px 16px 16px 0`，页面示例3 使用 `PAGE_FRAME_CONTENT_WITH_TOPBAR_MARGIN = 0 16px 16px 0`；⛔ 禁止给 NavBar 右侧额外加左 padding；⛔ 禁止 `max-w-* mx-auto` 居中容器；⛔ 禁止 `max-w-screen-xl` / `max-w-7xl` 收窄值（详见 [CHECKLIST.md §13](./CHECKLIST.md)）
9. **Card 颜色映射**：父容器灰底 → `Card color="white"`；父容器白底 → `Card color="grey"`（避免白叠白）。
10. **可运行交付**：输出完整 JSX 与文件路径级改动说明，保证 `npm run dev` 直接看到结果。

---

## 3. 生成后自检（必做）

完整 13 章自检见 [CHECKLIST.md](./CHECKLIST.md)；常见失败模式与修复见 [COMMON_FAILURES.md](./COMMON_FAILURES.md)。生成前已按命中场景读取相关章节，交付前仍要完整自检；**任一项不满足，先改再交付。**

最高频四个硬门禁（必过）：

- ⚡ **铁律自检**：整页无"自己手搓"的相似组件；无"只复用样式片段"的伪组件；FormTitle 真伪五件套全过（[CHECKLIST.md §8](./CHECKLIST.md)）；token 全部走 var，无硬编码 / 任意值
- 🧱 **白卡铁律**：最外层白卡纯白底 + 12px 圆角，⛔ 无 `border` / `outline` / `ring` / `shadow`
- 🪜 **滚动模型**：根容器 `h-dvh + overflow-hidden`；NavBar 命中即 `flex-row`；多面板/Playground 走嵌套骨架（[CHECKLIST.md §11](./CHECKLIST.md)），不整页滚
- 📐 **页面 header 灰底裸放**：标题/描述/操作按钮直接坐灰底，⛔ 不被白卡包住（[CHECKLIST.md §12](./CHECKLIST.md)）

---

## 4. 隔离保证（按需调用时生效）

`@tfdesign/b-end` 可与项目内任何其他资源共存。AI 工具**不会**因为安装了这个包就把 TFDS 规范应用到所有对话——只有用户明确表达 TFDS / b-end / 设计系统意图，或当前项目已接入 `@tfdesign/b-end` 且任务是 UI 生成时，规范才生效。

| IDE              | 调用指令                                      | 隔离原理                                                         |
| ---------------- | ----------------------------------------- | ------------------------------------------------------------ |
| **Cursor**       | `/产品设计-体服平台B端-界面生成`                                   | 本文件已设 `disable-model-invocation: true`；Cursor 不会自动纳入对话，仅显式触发 |
| **Codex**        | `/产品设计-体服平台B端-界面生成` 或 `@.agents/skills/产品设计-体服平台B端-界面生成/SKILL.md` | 隔离靠"不放入 `AGENTS.md`"维护；⛔ 禁止把 TFDS 内容写入项目根 `AGENTS.md`        |
| **Claude Code**  | `/产品设计-体服平台B端-界面生成`                                   | 通过 `.claude/skills/产品设计-体服平台B端-界面生成/` 显式加载                               |
| **Trae CN**      | `Use Skill: 产品设计-体服平台B端-界面生成`                         | 通过 `.trae-cn/skills/产品设计-体服平台B端-界面生成/` 显式加载；⛔ 禁止放进 `.trae/rules/`（always-on 目录） |
| **其它 Agent IDE** | `@` 引用本文件 / `AI_READ_FIRST.md`            | 通用原则：放在按需引用知识库，不要放进全局 prompt / 项目规则                          |

**Trae CN 自动设置**：一键安装会同步 `.trae-cn/skills/产品设计-体服平台B端-界面生成/`，重新打开项目 / 新开会话后使用 `Use Skill: 产品设计-体服平台B端-界面生成`；若 IDE 未刷新到 Skill，请确认该目录存在且包含 `SKILL.md`、`components.summary.json`、`components.index.json`。

> **Cursor 规范**（[Agent Skills](https://cursor.com/docs/context/skills)）：`name` 必须与父文件夹名 `产品设计-体服平台B端-界面生成` 一致；已设 `disable-model-invocation: true` 确保不自动触发。

---

## 5. 集成与契约自检命令

```bash
# 集成检测（只读，检查 theme.css 引入、@source 扫描、Skill 目录）
node node_modules/@tfdesign/b-end/scripts/check-tfds-integration.mjs

# 契约自检（只读，扫描 #hex、任意值、间距漂移等）
node node_modules/@tfdesign/b-end/scripts/check-tfds-contract.mjs
```

---

## 6. 与单组件 Skill 的关系

若项目中另有「ChatInput」等**单组件** zip Skill，与本 Skill **不冲突**：本【TFDS】总控 Skill 负责**整页编排与全量组件选型**；`components.summary.json` 负责快速定位，细节 props / rules / examples 仍以 `components.index.json` 命中条目为准。两者描述歧义时，以本 Skill + 包内索引为准。

---

**版本**：与本目录 `components.index.json` / `components.summary.json` 同步迭代（由主仓 `npm run generate:tfds-b-end-bundle` 生成）。升级 `@tfdesign/b-end` 后若需更新 Skill：删除 `.cursor/skills/产品设计-体服平台B端-界面生成` 后重新执行 `npm i`，或手动复制 `node_modules/@tfdesign/b-end/skills/产品设计-体服平台B端-界面生成`（npm 2.0.0 及更早为 `skills/tfds`）到 IDE 的 `skills/产品设计-体服平台B端-界面生成` 目录。
