# @tfdesign/b-end（B 端组件库 · 可安装包）

这个包的目标：**让对方在任意 Cursor + Vite/React 项目里安装后，可以直接 `import { … } from '@tfdesign/b-end'` 使用**与 TFDS 平台一致的 **B 端全量组件**（见包内 `src/index.js`）、**页面模板 / PATTERNS**，并拿到与 TFDS 一致的 **Token / theme.css**。

> **独立 npm 安装**：发布时 `prepack` 会把主仓 `src/data/systems/b-end/` 打包到包内 `src/_b_end_runtime/`，因此对方 `npm i @tfdesign/b-end` 后**不必 clone 主仓库**即可解析组件源码。

---

## 👀 你是谁？跳到对应章节


| 角色                                              | 你想做什么                             | 跳到                                               |
| ----------------------------------------------- | --------------------------------- | ------------------------------------------------ |
| 🎨 **设计师 / PM**                                 | 了解 TFDS 是什么、解决什么问题（**不需要写代码**）    | [§ 设计师视角：TFDS 在做什么？](#设计师视角tfds-在做什么)            |
| 👨‍💻 **前端工程师（已有项目）**                           | 装包 → 用组件                          | [§ TL;DR：安装即完成](#tldr安装即完成全自动)                   |
| 👨‍💻 **前端工程师（空项目）**                            | 从零搭一个 Vite + React + TFDS         | [§ 全新项目？从这里开始](#全新项目从这里开始)                       |
| 🤖 **AI / IDE（Cursor / Codex / Trae / Claude）** | 我已被自动配置 → Cursor/Claude/Codex 用 `/产品设计-体服平台B端-界面生成`；Trae CN 用 `Use Skill: 产品设计-体服平台B端-界面生成` | `[skills/产品设计-体服平台B端-界面生成/SKILL.md](./skills/产品设计-体服平台B端-界面生成/SKILL.md)` |
| 🛠️ **TFDS 维护者**                                | 发布新版本到 npm 仓库                     | `.cursor/skills/npm-publisher/SKILL.md`（主仓维护，不随 npm 包下发） |


---

## 设计师视角：TFDS 在做什么？

> 给设计师 / PM / 没装过开发环境的同学读，**不涉及任何代码**。

**TFDS 是一套"可被 AI 直接调用"的 B 端组件库 + 设计规范**。它解决的核心问题是：

1. **AI 不再"凭感觉画"** —— 我们把所有按钮、表单、表格、聊天输入框等组件，连同它们的颜色、字号、间距规则，全部封装成 AI 能"看懂"的指令字典（`skills/产品设计-体服平台B端-界面生成/`）。
2. **设计师改 Figma = 全平台同步** —— 你只需要在 Figma 里维护组件，工程会自动读取最新规则；AI 生成的页面会和你的设计稿保持一致。
3. **分层规范链路，覆盖所有场景**：
  - **设计原则层**：AI 先判断页面气质、UX 取舍、视觉权重和组件角色
  - **页面范式层**：AI 先判断是列表管理、详情编辑、会话工作台、入口首页还是多步骤配置
  - **组件层**：AI 先读轻量摘要选型，再回查完整组件索引（Button、Card、Tabs…）
  - **布局层**：页面骨架怎么搭（一栏 / 两栏 / IM 聊天 / 工作台…）
  - **token 层**：组件没覆盖的自定义区块，AI 必须用什么颜色/字号/圆角

📂 **你只需要优先打开这些文件浏览，就能看到规范如何约束 AI**：

- `[skills/产品设计-体服平台B端-界面生成/DESIGN_PRINCIPLES.md](./skills/产品设计-体服平台B端-界面生成/DESIGN_PRINCIPLES.md)` — 设计原则、页面气质与 UX 取舍
- `[skills/产品设计-体服平台B端-界面生成/PAGE_ARCHETYPES.md](./skills/产品设计-体服平台B端-界面生成/PAGE_ARCHETYPES.md)` — 页面范式与信息架构选型
- `[skills/产品设计-体服平台B端-界面生成/LAYOUT_RECIPES.md](./skills/产品设计-体服平台B端-界面生成/LAYOUT_RECIPES.md)` — 页面 recipe、容器语义、间距和对齐决策
- `[skills/产品设计-体服平台B端-界面生成/LAYOUT_RULES.md](./skills/产品设计-体服平台B端-界面生成/LAYOUT_RULES.md)` — 页面骨架规则
- `[skills/产品设计-体服平台B端-界面生成/GLOBAL_DESIGN_RULES.md](./skills/产品设计-体服平台B端-界面生成/GLOBAL_DESIGN_RULES.md)` — 全局 token 规则

> 💡 后续 TFDS 平台会把这些规范以可视化形式展示，设计师无需阅读 markdown 也能理解。

---

## 全新项目？从这里开始

如果你还没有业务项目（空文件夹或仅有 IDE 工作区），在目标目录执行一键安装向导。脚本会自动判断：已有项目则复用现有工程，空文件夹则创建最小 Vite + React 项目、安装 Tailwind v4、从 npm 安装 `@tfdesign/b-end` 并同步 Skill。

### 推荐：一条命令完成

```bash
npx -y -p @tfdesign/b-end@latest tfds-b-end-setup
```

如果需要在其他目录安装到指定项目：

```bash
npx -y -p @tfdesign/b-end@latest tfds-b-end-setup -- --target "/绝对路径/.../业务项目根"
```

安装完成后，`postinstall` 会自动配置 CSS 与 Cursor / Claude / Codex / Agents Skill，直接进入 [TL;DR：安装即完成](#tldr安装即完成全自动) 后的使用环节。

---

## TL;DR：安装即完成（全自动）

`npm install` 完成后，`postinstall` 会自动执行下面几件事，**无需任何手动配置**：


| #   | 自动完成                                     | 目标位置                                               |
| --- | ---------------------------------------- | -------------------------------------------------- |
| 1   | 复制 Cursor Skill                          | `.cursor/skills/产品设计-体服平台B端-界面生成/`（Agent 输入 `/产品设计-体服平台B端-界面生成` 唤起）        |
| 2   | 复制 Claude Code Skill                     | `.claude/skills/产品设计-体服平台B端-界面生成/`（输入 `/产品设计-体服平台B端-界面生成` 唤起）              |
| 3   | 写入 Codex 项目内参考 Skill                     | `.codex/skills/产品设计-体服平台B端-界面生成/` |
| 4   | （可选）Codex 用户级 Skill                       | 默认**不**写入 `~/.codex/skills/`；需全局时设 `TFDS_CODEX_GLOBAL=1` 后重新 `npm i` |
| 5   | 复制 Agents Skill 兜底                       | `.agents/skills/产品设计-体服平台B端-界面生成/`（通用 agent 客户端）               |
| 6   | 复制 Trae CN Skill                           | `.trae-cn/skills/产品设计-体服平台B端-界面生成/`（Use Skill: 产品设计-体服平台B端-界面生成）                |
| 7   | **插入 `theme.css` import 与 `@source` 扫描** | `src/index.css`（首个含 `@import "tailwindcss"` 的候选文件） |


⚠ **故意不自动写入 `.trae/rules/`**：Trae rules 是 always-on 全局规则，与 TFDS"显式调用才生效"的隔离原则冲突。Trae CN 使用 `.trae-cn/skills/产品设计-体服平台B端-界面生成/` 作为按需 Skill 目录，重新打开项目 / 新开会话后使用 `Use Skill: 产品设计-体服平台B端-界面生成`。

Skill 目录内的关键文件：

- `SKILL.md`：总控流程、调用优先级、黄金流程。
- `DESIGN_PRINCIPLES.md` / `PAGE_ARCHETYPES.md`：设计品味、页面范式、布局判断。
- `components.summary.json`：轻量组件摘要，用于快速初选组件和模板。
- `components.index.json`：完整组件详情，命中后读取 props / rules / examples。
- `CHECKLIST.md` / `COMMON_FAILURES.md`：交付前自检与高频问题修正。

> **前提**：使用 `npx … tfds-b-end-setup` 时，空文件夹与已有项目均可；若仅执行 `npm i @tfdesign/b-end`，需位于业务项目根且入口 CSS 中已有 `@import "tailwindcss";`（否则由 setup 或 postinstall 提示补齐）。
>
> ⚠ 不要在 `@tfdesign/b-end` 包自身目录里安装；不要从 `tmp-*/` 临时目录安装（清理后路径 `ENOENT`）。

### 安装方式（npm 官网）

- **一键向导（推荐，含空项目初始化）**
  ```bash
  npx -y -p @tfdesign/b-end@latest tfds-b-end-setup
  ```
- **仅安装依赖（已有完整 Vite + Tailwind 项目）**
  ```bash
  npm i react react-dom lucide-react "@tfdesign/b-end@latest" --save
  ```

### postinstall 自动写入 CSS 的效果

脚本在 `@import "tailwindcss";` 之后自动插入（已存在则跳过，不重复写入）：

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

若入口 CSS **未找到** `@import "tailwindcss"` → 不改写文件，终端打印手动步骤提示。

### 跳过自动操作（可选）

```bash
# 跳过 CSS 自动补丁（保持 CSS 文件不变）
SKIP_TFDS_CSS_PATCH=1 npm i "@tfdesign/b-end" --save

# 跳过 Skill 复制（如 CI 环境只需依赖不需 IDE Skill）
SKIP_TFDS_CURSOR_SKILL=1 npm i "@tfdesign/b-end" --save
```

### 安装后验证（可选，只读）

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

---

## 2) 引入主题（postinstall 已自动完成，此节供手动回退参考）

若 postinstall 未自动写入（例如 CSS 中尚无 `@import "tailwindcss"`），请手动在全局样式入口（如 `src/index.css`）中补充：

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

/* Tailwind v4 推荐 @source（与 tailwind.config content 二选一） */
@source "./**/*.{js,jsx,ts,tsx}";
@source "../node_modules/@tfdesign/b-end/**/*.{js,jsx}";
```

> `theme.css` 包含 `@theme { ... }` 的完整 token 定义（由 TFDS 的 `generateThemeCssVars()` 生成）。

---

## 3) Tailwind 扫描说明

若你仍使用 `tailwind.config` 的 `content` 方式（Tailwind v3 / 旧项目），在配置里加入：

```js
export default {
  content: [
    './index.html',
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@tfdesign/b-end/**/*.{js,jsx}',
  ],
};
```

> 与 `@source` 二选一，不要同时使用。

---

## 4) 使用组件

**选型先看随包 Skill 的 `skills/产品设计-体服平台B端-界面生成/components.summary.json`，具体 props / rules / examples 以 `skills/产品设计-体服平台B端-界面生成/components.index.json` 命中条目为准**（全量组件含 Avatar、NavBar、Table、Modal、ChatInput、ChatMessage 等）。

头像类组件默认使用包内本地成员头像素材：`Avatar` 图片态未传 `src` 时会随机取本地成员头像；需要稳定绑定时可从包内导出的 `getTeamMemberByIndex` / `getTeamAvatarBySeed` 获取本地头像后传给 `avatarSrc`。不要为默认头像使用 pravatar / Unsplash / placeholder 外链。

```jsx
import { NavBar, Button, Table, ChatInput } from '@tfdesign/b-end';

export default function Demo() {
  return (
    <div className="flex min-h-screen flex-col gap-4 p-6">
      <NavBar platform="ola" selectedItemId="knowledge" />
      <Button variant="primary">主操作</Button>
      <ChatInput variant="default" />
    </div>
  );
}
```

### 4.1 页面模板：IM 对话（静态片段）

```jsx
import { IMConversationPattern } from '@tfdesign/b-end';

export default function ImDemoPage() {
  return (
    <div className="p-6" style={{ background: 'var(--color-blueGrey-200)' }}>
      <IMConversationPattern />
    </div>
  );
}
```

> 重要：`IMConversationPattern` 会间接依赖 `ChatBubble → Avatar/Tooltip/...` 等链路。请确保 Tailwind 扫描覆盖到包内所有 `.jsx`（`node_modules/@tfdesign/b-end/**/*.{js,jsx}` 通常足够）。

---

## 5) Cursor Agent Skill `产品设计-体服平台B端-界面生成`（`/产品设计-体服平台B端-界面生成` 唤起）

安装包时 `postinstall` 已自动复制 Skill 到 `.cursor/skills/产品设计-体服平台B端-界面生成/`。

### 5.1 安装后会发生什么

- 若 `.cursor/skills/产品设计-体服平台B端-界面生成/` 不存在 → 自动复制包内 `skills/产品设计-体服平台B端-界面生成/` 到项目根的中文 Skill 目录
- 若目录已存在 → **不覆盖**，终端提示 skipped
- 若仅有旧英文目录或旧大写目录 → 自动清理旧目录并同步到 `产品设计-体服平台B端-界面生成/`

### 5.2 跳过自动释放

```bash
SKIP_TFDS_CURSOR_SKILL=1 npm i @tfdesign/b-end
```

### 5.3 用户如何在 Cursor 里唤起（`/产品设计-体服平台B端-界面生成`）

1. 安装完成后，先重新打开项目或新开 Agent 会话，让 Cursor 重新扫描 `.cursor/skills/产品设计-体服平台B端-界面生成/`。
2. 在 **Agent** 聊天输入框输入 `/产品设计-体服平台B端-界面生成`，从列表中选择本 Skill（描述含「产品设计-体服平台B端-界面生成」）。
3. 若列表没有 `产品设计-体服平台B端-界面生成`，先确认 `.cursor/skills/产品设计-体服平台B端-界面生成/SKILL.md` 存在，再重启 Cursor。
4. 继续描述要生成的页面（例如「做一个带 IM 会话区 + 底部 ChatInput 的客服页」）。
5. 模型必须先读取 `.cursor/skills/产品设计-体服平台B端-界面生成/components.summary.json` 初选组件，再回查 `.cursor/skills/产品设计-体服平台B端-界面生成/components.index.json` 命中条目写 props。

### 5.4 与单组件 Skill 的关系

- `产品设计-体服平台B端-界面生成`（/产品设计-体服平台B端-界面生成）：总控 Skill，索引里包含 **ChatInput + IMConversationPattern** 等，适合「直接生成页面」。
- **单组件 zip**：仍可按需额外解压到 `.cursor/skills/...`，与 `产品设计-体服平台B端-界面生成` 不冲突；若规则冲突，以 `产品设计-体服平台B端-界面生成` + 本包 `components.index.json` 命中条目为准。

### 5.5 手动安装 / 平台下载

- **手动**：从本仓库复制 `packages/tfds-b-end/skills/产品设计-体服平台B端-界面生成` → 对方项目 `.cursor/skills/产品设计-体服平台B端-界面生成`。
- **平台**：亦可在 TFDS Skill 中心下载 **产品设计-体服平台B端-界面生成** 对应 zip，解压到 `.cursor/skills/产品设计-体服平台B端-界面生成/`（**目录名须为 `产品设计-体服平台B端-界面生成`**，否则 `/产品设计-体服平台B端-界面生成` 无法命中）。

---

## 5.6) 给 AI / Agent 的规范入口

TFDS 规范只应在显式调用时读取，**不要**放进 `AGENTS.md`、`.trae/rules/` 等 always-on 规则。

- **首选入口**：`/产品设计-体服平台B端-界面生成` 或 `@产品设计-体服平台B端-界面生成` → `skills/产品设计-体服平台B端-界面生成/SKILL.md`
- **设计原则**：`skills/产品设计-体服平台B端-界面生成/DESIGN_PRINCIPLES.md`
- **页面范式**：`skills/产品设计-体服平台B端-界面生成/PAGE_ARCHETYPES.md`
- **布局 Recipe**：`skills/产品设计-体服平台B端-界面生成/LAYOUT_RECIPES.md`
- **组件轻量摘要**：`skills/产品设计-体服平台B端-界面生成/components.summary.json`
- **组件权威索引**：`skills/产品设计-体服平台B端-界面生成/components.index.json`
- **交付自检 / 失败修正**：`skills/产品设计-体服平台B端-界面生成/CHECKLIST.md` / `skills/产品设计-体服平台B端-界面生成/COMMON_FAILURES.md`
- **跨 IDE 兜底入口**：`AI_READ_FIRST.md`
- **深层规则**：由 `SKILL.md` 按需引导读取 `LAYOUT_RECIPES.md`、`LAYOUT_RULES.md` 与 `GLOBAL_DESIGN_RULES.md`

### 各 IDE 调用方式


| IDE                | 调用方式                                                                                    | postinstall 是否自动配置                     |
| ------------------ | --------------------------------------------------------------------------------------- | -------------------------------------- |
| **Cursor**         | 重新打开项目 / 新开 Agent 会话后输入 `/产品设计-体服平台B端-界面生成`；若未出现，确认 `.cursor/skills/产品设计-体服平台B端-界面生成/SKILL.md` 后重启 Cursor          | ✅ `.cursor/skills/产品设计-体服平台B端-界面生成/`               |
| **Claude Code**    | 重启 Claude Code 会话后输入 `/产品设计-体服平台B端-界面生成`；若不支持 Skill 热加载，直接引用 `skills/产品设计-体服平台B端-界面生成/SKILL.md`                     | ✅ `.claude/skills/产品设计-体服平台B端-界面生成/`               |
| **Codex**          | 新开/重启 Codex 会话后输入 `/产品设计-体服平台B端-界面生成`；优先使用项目内 `.codex/skills/产品设计-体服平台B端-界面生成/`                  | ✅ `.codex/skills/产品设计-体服平台B端-界面生成/`（用户级 `~/.codex/skills/` 默认不写入，需 `TFDS_CODEX_GLOBAL=1`） |
| **Trae**           | 重新打开项目 / 新开会话后使用 `Use Skill: 产品设计-体服平台B端-界面生成`；若不支持 Skill 列表，则把 `node_modules/@tfdesign/b-end/skills/产品设计-体服平台B端-界面生成/` 作为按需知识库引用 | ❌ 故意不写 `.trae/rules/`（避免 always-on 污染） |
| **其他 IDE / Agent** | 不保证支持 `/产品设计-体服平台B端-界面生成`；显式让 AI 先读 `AI_READ_FIRST.md`，再按其指引读取 `skills/产品设计-体服平台B端-界面生成/SKILL.md`                    | —                                      |


> 输入 `/` 后没看到 `产品设计-体服平台B端-界面生成` 选项？先确认项目内 `.cursor/skills/` 或 `.codex/skills/` 下对应目录存在；再「重启 IDE / 重新打开项目」让 IDE 重新扫描 Skill 目录。若本机仍有历史 `~/.codex/skills/产品设计-体服平台B端-界面生成/`，建议删除以免空项目误触发。

---

## 6) 硬门禁：ESLint（`@tfdesign/b-end/eslint`）

仅靠 Skill 无法从工程上禁止 AI/人写出"漂移样式"。ESLint preset **随本包版本分发**，请让对方项目安装：

```bash
npm i -D eslint @eslint/js eslint-plugin-react eslint-plugin-react-hooks globals @tfdesign/b-end
```

新增 `eslint.config.js`：

```js
import tfds from '@tfdesign/b-end/eslint';
export default [...tfds];
```

并在 CI 中执行：

```bash
npx eslint .
node node_modules/@tfdesign/b-end/scripts/check-tfds-contract.mjs
```

| 工具 | 作用 |
|------|------|
| `@tfdesign/b-end/eslint` | spacing 白名单、禁止任意值 class、**锁定页面范式模板**（禁止传 `className`） |
| `check-tfds-contract.mjs` | 启发式漂移提示（未装 ESLint 时的兜底） |

规则事实源：`scripts/eslint/`（由 `npm run build:tfds-eslint-assets` 生成各包 `eslint/`）。
