@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 在做什么？ | | 👨‍💻 前端工程师（已有项目） | 装包 → 用组件 | § TL;DR：安装即完成 | | 👨‍💻 前端工程师（空项目） | 从零搭一个 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。

推荐：一条命令完成

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

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

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

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

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 官网）

• 一键向导（推荐，含空项目初始化）

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

• 仅安装依赖（已有完整 Vite + Tailwind 项目）

  npm i react react-dom lucide-react "@tfdesign/b-end@latest" --save

postinstall 自动写入 CSS 的效果

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

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

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

跳过自动操作（可选）

# 跳过 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

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

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

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

若 postinstall 未自动写入（例如 CSS 中尚无 @import "tailwindcss"），请手动在全局样式入口（如 src/index.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 / 旧项目），在配置里加入：

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 外链。

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 对话（静态片段）

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 跳过自动释放

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 随本包版本分发，请让对方项目安装：

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

新增 eslint.config.js：

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

并在 CI 中执行：

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/）。