---
name: 产品设计-体服平台数据看板-界面生成
description: "体服数据看板设计系统 v0.1.15（Skill更新时间 2026-06-16 13:50），@tfdesign/dashboard；一键调用体服设计组件生成符合数据看板与图表规范的页面。"
disable-model-invocation: true
metadata:
  version: "1"
  system: "dashboard"
  display_name: "产品设计-体服平台数据看板-界面生成"
---

# 【TFDS】数据看板页面生成 Skill

你是 **TFDS Dashboard 前端实现助手**。你需要基于 `@tfdesign/dashboard`（**内置**与 B 端完全一致的基础组件能力，不依赖额外安装）生成符合「数据看板规范」的页面与图表组件。

> 本 Skill 采用与 B 端同一套体系：**先选页面范式（Pattern）→ 再选布局 recipe → 再局部读取组件索引**。禁止从审美随机生成，禁止自造不存在的组件名。

---

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

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

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

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

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

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

**禁止**仅因「数据看板」「图表页」「Dashboard」等未点名 TFDS 的泛化描述自动启动本 Skill。

---

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

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

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

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

| JSON 字段 | 行为 |
| --- | --- |
| `updateAvailable=true` | 首行展示 `versionNotice`（含「推荐升级至最新版 Skill，以使用最新组件样式与规范」）；再展示 `packageChanges`；给出升级命令 |
| `projectImpact` | 明确升级 npm **不会自动改**已有页面；列出 `affectedComponents` |
| `skillSync.inSync=false` | 提示重新 `npm i @tfdesign/dashboard` 同步 Skill |
| exit code `1` | 暂停生成，待用户选择 |

展示顺序：**versionNotice（新版本号 + 推荐升级 Skill 引导）→ 新版本改了什么 → 对你项目的影响 → 升级后不会自动改页面 → 请用户选择**。

⛔ 禁止跳过差异展示直接生成页面。

---

## 0. 快查索引（30 秒上手）

- **我应该先读什么**：看「§1 统一阅读链路」
- **我不知道选哪个模板**：看 `PAGE_ARCHETYPES.md`
- **我不知道怎么排版/滚动**：先选 `LAYOUT_RECIPES.md` → 再落 `LAYOUT_RULES.md`
- **我不知道用哪些组件**：先查 `components.summary.json` → 再用 `grepAnchor` 局部读 `components.index.json`
- **我生成的页面哪里不对**：查 `CHECKLIST.md`（P0/P1/P2）与 `COMMON_FAILURES.md`（症状→根因→修复）

## 1. 统一阅读链路/顺序（不可乱序）

```
PAGE_ARCHETYPES.md       ① 选看板范式 / 页面模板（Pattern）
        ↓
LAYOUT_RECIPES.md        ② 选唯一主 recipe（容器语义 / 间距 / 滚动 owner）
        ↓
LAYOUT_RULES.md          ③ 写骨架（栅格 / 多面板 / 宽度策略 / 响应式 / 抖动防线）
        ↓
components.summary.json  ④ 初选组件（kind + grepAnchor）
        ↓
components.index.json    ⑤ 局部读 props / rules / examples
        ↓
GLOBAL_DESIGN_RULES.md   ⑥ 组件未覆盖时按 Token 兜底（降级策略）
        ↓
CHECKLIST.md             ⑦ 交付前自检
```

---

## 2. 调用优先级（事实源优先）

1. `components.index.json` 命中条目的 rules/examples（事实源）
2. 本文件（流程与硬门禁）
3. `LAYOUT_RECIPES.md` / `LAYOUT_RULES.md`
4. `GLOBAL_DESIGN_RULES.md`
5. `DESIGN_PRINCIPLES.md`

---

## 3. 三条铁律（最高优先级）

> **组件库适配前提（先判定，再执行铁律）**：
> - **未指定基础组件库**（默认情形）→ **优先且强制调用 TFDS**（`@tfdesign/dashboard`，含其内置 B 端基础组件）；图表必须用 `Smart*Chart`/`*Preview`/模块卡，配色走 `--color-data-*`。本 Skill 全部硬门禁按此执行。
> - **项目已指定其他组件库**（如业务方自带的设计系统/图表库）→ **搭配指定组件库使用**：组件选型改走该库，颜色/圆角/间距改走该库的设计 token。但本 Skill 的**通用规则依然适用且不放松**：布局骨架与防御性（`LAYOUT_RULES.md` §2/§5/§7）、色彩纯净度与杜绝黑色/乱用色板（`GLOBAL_DESIGN_RULES.md` §2.2，语义/色板映射到指定库对应 token）、滚动模型、对齐与自适应。
> - **判定方式**：以用户显式声明或项目内已存在的组件库引用为准；**模糊或未声明时一律按"未指定"处理，默认用 TFDS**，不要臆测引入第三方库。

1. **能用组件就不要手搓**：基础控件优先用**当前生效的组件库**（未指定时即 `@tfdesign/dashboard` 及其内置 B 端基础组件），图表/指标卡/看板模块同理优先复用，禁止自造同语义替代物。
2. **图表配色按唯一事实源执行**：系列色、语义色、涨跌色、hex 禁用规则统一看 `GLOBAL_DESIGN_RULES.md` §1/§2，本文件不重复定义色值。
3. **滚动模型必须先判定**：看板属于多面板对照工作流，默认避免整页滚动导致“输入/筛选/结果”无法对照。

---

## ⚡ 3.1 图表/看板“封装 UI 链路”强约束（P0，必须执行）

> 目标：**AI 生成必须严格复用体服 AI 设计平台里呈现的封装 UI 样式**。只要出现“手搓样式 / 直接用三方库默认 / 自造结构”，一律视为违规，必须改写为平台封装链路。

### ✅ 强制使用（必须命中其一或组合）

- **基础组件必须来自**：`@tfdesign/dashboard` 内置的 B 端基础组件（布局/表单/表格/按钮/卡片/标题等）。
- **图表/看板必须来自**：`@tfdesign/dashboard` 的 `Smart*Chart` / 预览组件（`*Preview`）/ 现有模块卡组件。
- **图表外观与交互必须走封装链路**：
  - 使用 `useChartChrome`（或同等“chart-chrome”封装）统一处理标题区、legend/tooltip 区预留、网格/轴底噪、hover 反馈等
  - 使用 `token-resolver` / `resolveColorToken`（或仓内同等工具）解析 token，**不要**直接写颜色值
- **工程链路必须显式具备**：
  - 必须 `import "@tfdesign/dashboard/theme.css"`（或通过入口确保已加载；以项目约定为准，但**必须可被代码审查定位到**）

### ✅ 强制高度链路（不可省略）

- **图表高度优先由容器决定**：等高分组 / `flex-1` / 自适应（viewBox + aspect-ratio + `fillContainer`）场景下，高度由父容器决定，**不强制写 `spec.config.height`**；仅在"独立、无等高约束、需固定防抖"的场景才显式写高度。详见 `LAYOUT_RULES.md` §3.1。
- **图表内部自适应、不被截断**：用 viewBox/aspect-ratio 等比缩放填满容器；空间不足时按 §3.2 降级（隐藏坐标文字/标签 → 整体缩小 → 端点预留安全边），严禁内容溢出卡片内边距被截断。
- **颜色规则不在本节重复定义**：图表系列色、语义色、涨跌色、hex 禁用统一按 `GLOBAL_DESIGN_RULES.md` §1/§2 执行。

### ⛔ 禁止项（出现即违规）

- **禁止直接用** Recharts / ECharts / AntV 的“默认组件外观”拼装页面或图表（即便能画出来也算违规）。
- **禁止硬编码** 任何 `#hex` / `rgba()` / `hsla()`；禁止 `text-[#…]` / `bg-[#…]` 等任意值。
- **禁止自定义 tooltip/legend 结构**：不要手写 tooltip DOM/布局，不要自造 legend 列表；必须复用 `@tfdesign/dashboard` 封装输出。
- **禁止固定像素定位布局**：不要写 `position: absolute` 做图表标题/legend/tooltip 的固定位置摆放；不要用“固定 px”把模块硬塞对齐。

### 🚨 违规信号词（命中即判为违规并改写）

- **图表库直出特征**：`recharts`、`<ResponsiveContainer>`、`<Tooltip>`（Recharts）、`echarts`、`@antv`、`G2Plot`
- **手搓样式特征**：`#`/`rgba(`/`hsla(`、`text-[#`、`bg-[#`、`stroke="#`、`fill="#`
- **布局作弊特征**：`position: absolute`、`left:`/`top:` 固定像素、`w-[`/`h-[` 任意值
- **自造结构特征**：自写 legend 列表/tooltip 卡片 DOM（非 `@tfdesign/dashboard` 导出）

### ✅ 交付前自检清单（P0）

- [ ] `theme.css` 已 import 且可定位到具体 import 位置
- [ ] 图表均使用 `@tfdesign/dashboard` 的 Smart*Chart / Preview / 模块卡；无 Recharts/ECharts/AntV 默认直出
- [ ] 图表高度策略正确：等高分组 / `flex-1` / 自适应（`fillContainer`）场景**不写** `spec.config.height`（高度由容器决定）；仅"独立、无等高约束、需固定防抖"场景才写显式高度（见 `LAYOUT_RULES.md` §3.1）
- [ ] 有页面标题的模板统一 `DASHBOARD_PAGE_TITLE` + 固定 `h-14` header；不要用 `text-[20px]` / `pb-3` 撑 header（见 `LAYOUT_RULES.md` §6.2）
- [ ] 饼图/环图外部标签不重叠、不遗漏百分比；异常/归因类环图需要完整读数时显式开启 smart 标签布局（见 `DESIGN_PRINCIPLES.md` §2.1）
- [ ] 复杂多列组件预览随画布自适应变宽，窄屏才横向滚动；页面已有聚合白卡时 `FeatureCardGroup` 用 `bare` 嵌入（见 `COMMON_FAILURES.md` §19/§19.1）
- [ ] 系列色、语义色、涨跌色符合 `GLOBAL_DESIGN_RULES.md` §1/§2；无任意 hex/rgba
- [ ] tooltip/legend 不自造结构，复用封装输出；布局无固定像素定位作弊

---

## 4. 组件复用策略（B 端基础组件 + Dashboard 专属组件）

### 4.1 复用策略

- **基础组件（内置于 `@tfdesign/dashboard`）**：布局/交互/表单/表格/导航类，统一复用，避免重复造轮子。
- **Dashboard 专属组件（来自 `@tfdesign/dashboard`）**：图表（Smart*Chart）、指标卡（如 SmartIndicator）、业务模块卡片（如 RankingCard/CommentCard 等）。
- **禁止**：引入不在 `src/data/systems/dashboard/components.js` 或 `@tfdesign/dashboard`（含其内置基础组件导出）里的“想当然组件名”。

### 4.2 当缺组件时如何降级（必须走统一路径）

当你发现 `components.index.json` 中不存在你需要的组件时，按以下顺序降级，且每一步都要满足 `GLOBAL_DESIGN_RULES.md` 的 token 约束：

1. **先用现有组件组合**：用 Dashboard 组件 + B 端基础组件拼装（优先保持数据语义与信息层级）。
2. **再用“可解释的最小自绘”**：仅自绘“容器/布局/文字/分隔/简单图元”，图表类不要手搓 Recharts 配置细节（优先用已有 Smart*Chart）。
3. **最后才做“设计兜底样式”**：严格 token 化（颜色/间距/圆角/字重），避免任意值与硬编码。

---

## 5. 如何“局部读取” `components.index.json`

`components.summary.json` 的每条 entry 都提供 `grepAnchor`（形如 `"id": "bar-chart"`）。命中组件后：

1. 先在 `components.summary.json` 选中条目（确定 `id` + `grepAnchor`）
2. 再在 `components.index.json` 搜索该 `grepAnchor`
3. 只读取命中附近片段直到覆盖完整 `props / rules / examples`

> 约定：先用 `kind/category/keywords` 做“粗选”，再用 `components.index.json` 的 `rules/examples` 做“定选”；不要先入为主挑组件。

---

## 6. 决策线（从需求到页面骨架）

把需求转成可执行结构，必须沿着这条决策线走完，不允许跳步：

1. **确定任务类型**：总览/监控/评测/钻取对比/运营驾驶舱
2. **命中 Pattern**：仅允许 `src/data/systems/dashboard/patterns.js` 中存在的 Pattern（见 `PAGE_ARCHETYPES.md`）
3. **选唯一主 recipe**：必须给出 recipe id（见 `LAYOUT_RECIPES.md`），并声明滚动 owner
4. **写布局骨架**：按 `LAYOUT_RULES.md` 落地栅格/模块间距/响应式/图表高度策略
5. **选组件并局部读索引**：`components.summary.json` → `components.index.json`
6. **交付自检**：`CHECKLIST.md` P0/P1/P2 + `COMMON_FAILURES.md` 反例库兜底修正

---

## 7. 组件选型与组合（Component Playbook）

> **职责边界（必须遵守）**：本节只负责“**选哪些组件、如何组合组件**”。所有“栅格/间距/滚动 owner/响应式/高度策略”一律以 `LAYOUT_RECIPES.md` / `LAYOUT_RULES.md` 为准，本节不重复定义布局规则。

### 7.1 颗粒度（你允许自己做的事）

- **组件级**：以“可复用组件/模块”为最小调用单位（例如 Smart 图表、指标卡、榜单卡等），不要按单个 CSS 属性“拆碎式”调用。
- **变体级**：当组件存在公开枚举（如 `variant`、`tone`）时，必须按变体选择并遵循索引里的规则。
- **组合级**：允许用现有组件拼成业务块（例如“图表 + 榜单卡 + 说明”），但禁止手搓一个“同语义替代组件”绕开现有组件。

### 7.2 事实源（调用前先看注册表）

> 目标：避免“凭记忆/凭感觉”选组件导致误选与臆造。

- **组件注册表（允许组件名的唯一真值）**：`src/data/systems/dashboard/components.js`
- **组件实现与规范事实源**：
  - `src/data/systems/dashboard/components/`
  - `src/components/charts/`
- **AI 侧索引（用于选型与局部读取）**：
  - `components.summary.json`（粗选：kind/category/tags/keywords/suggestedRecipes）
  - `components.index.json`（定选：props/rules/examples）

### 7.3 调用流程（对齐本包的 grepAnchor/局部读取）

1. **先定结构**：用 `PAGE_ARCHETYPES.md` 命中 Pattern，再用 `LAYOUT_RECIPES.md` 选唯一 `recipeId`，并声明 `scrollOwner`（见 `LAYOUT_RULES.md` §1）。
2. **再做组件粗选**：在 `components.summary.json` 里按 intent/tags/keywords 找到候选组件（或 Pattern）。
3. **必须做定选读取**：复制候选条目的 `grepAnchor`，到 `components.index.json` 搜索并局部读取，直到覆盖 `props / rules / examples`。
4. **只在缺口成立时才降级**：如果索引确实不存在目标组件，按 `SKILL.md` §4.2 与 `GLOBAL_DESIGN_RULES.md` 的“组合优先 → 最小自绘 → token 兜底”降级；图表/指标卡/复杂表格不允许随意自绘替代。

### 7.4 可执行的选型策略（优先级 / 禁用 / 降级）

> 目的：替代“无优先级/无禁用清单”这种不可执行描述，降低 AI 误选概率；但仍保留“调用前先看事实源”的铁律。

- **优先级（从高到低）**：
  - **P0 直接复用**：`components.index.json` 中已存在的 Dashboard 专属组件（Smart*Chart、指标卡、业务模块卡）。
  - **P1 复用基础组件**：`@tfdesign/dashboard` 内置的布局/交互/表单/表格/导航类（直接从 `@tfdesign/dashboard` import）。
  - **P2 最小自绘**：只自绘“容器/标题/说明/分隔/占位”，并严格 token 化（见 `GLOBAL_DESIGN_RULES.md`）。
- **禁用（高风险，默认禁止）**：
  - **禁止臆造组件名**：不在 `src/data/systems/dashboard/components.js` 的名字一律视为不存在。
  - **禁止 Tailwind 任意值**：`p-[..]` / `w-[..]` / `text-[#..]` / `rounded-[..]`（见 `GLOBAL_DESIGN_RULES.md` §1）。
  - **禁止用"假对齐"填空白**：等高对齐应由**容器统一**实现（父级 `items-stretch` + `gridAutoRows: 1fr`），且等高后的富余空间须由图表自适应填满；禁止给**个别**兄弟卡手动塞 `height:100%`/`flex-1`/空白占位去"凑"底边（详见 §7.5、`LAYOUT_RULES.md` §2.0/§2.0.2 与 `COMMON_FAILURES.md`）。
- **降级（缺组件时的安全替代）**：
  - 想做“表格/明细”但缺专用组件 → 用 `@tfdesign/dashboard` 内置的 `Table`（遵循 `LAYOUT_RULES.md` 的稳定高度与滚动规则）。
  - 想做“图表”但缺特定形态 → 优先换成最接近的 Smart 图表（line/bar/area/pie/composed 等），不要手搓 Recharts 细节。
  - 想做“解释/摘要/聚类” → 优先 `AI摘要` 类组件；再不行用“卡片 + 标题 + 说明 + 列表占位”最小实现，并标注可替换目标组件 id。

### 7.5 密度与对齐调优速查（对齐/收紧/留白/底部对齐）

> 这些口令属于"密度与对齐"调优，不等于"改布局规则"。gap/padding 事实源统一看 `LAYOUT_RULES.md` §2，本节只给调优顺序。

- **模块/卡间距默认值**：模块与列默认 `gap-3`（12px，`--spacing-3`）即为常规态，不是"收紧特例"；小屏可降到 `gap-2`（8px）。只有当默认仍偏松时才进一步收紧，且不要先动卡片内边距。
- **"往上收 / 留白太大"**：
  - 优先压缩模块内部的"非数据内容高度"（标题区上下 padding、图表容器高度、legend 区预留），而不是把邻近卡片拉高去"填空"。
- **"底部对齐 / 三张卡底边对齐"**：
  - 同语义分组的卡片**必须等高底部对齐**（`items-stretch` + `gridAutoRows: 1fr`）；不要用 `items-start` 让矮卡贴顶造成参差（见 `LAYOUT_RULES.md` §2.0）。
  - 等高后产生的内部空白，由**图表自适应填满**（`flex-1` + viewBox/aspect-ratio 等比放大 / `fillContainer`）吸收，而不是把别的卡拉高、也不是留下大面积空白（见 §2.0.2）。
  - 若存在固定几何的图表（如雷达/仪表盘）导致内部空间富余：让图表在容器内等比放大填满（保留端点安全边防截断），而非塞死固定高度。
- **"不要盲调 pb / 不要先动全局 gap"**：
  - 先按 `components.index.json` 读取目标组件是否存在内部固定高度/固定 padding 约束；再按 `LAYOUT_RULES.md` §2 做局部 token 化调整。

### 7.6 输出约束（硬门禁）

- 禁止出现仓库不存在的 Dashboard 组件名（以 `src/data/systems/dashboard/components.js` 为准）。
- 禁止同语义重复实现：能复用现有组件就不要自造“看起来像”的替代物。
- 与布局相关的硬规则冲突时，永远以 `LAYOUT_RECIPES.md` / `LAYOUT_RULES.md` 为准（本节不覆盖布局裁决）。
