# Prompt — T2 样板 Tooltip 扩展（按已定 schema 扩展实例）

> **角色**：executor
> **范围**：T2 样板第 2 个组件 Tooltip——按 [`docs/internal/_plans/t2-sample-badge-plan.md`](../../_plans/t2-sample-badge-plan.md) 已锁的 schema/contract/audit 范式扩展实例（不改 schema）。
>
> ⚠️ **不要 commit / 不要 git add**——dirty 累积到 milestone。
> ⚠️ 完成后 **STOP**，按底部"完成报告"格式回报。
> ⚠️ **不扩范围**：本轮只做 Tooltip——不动 Select / 其它 page / canonical Tooltip / canonical Badge / 已 commit 的 schema 文件 (`types.ts`)。
> ⚠️ 如发现裁定与代码事实冲突的 **blocker**（不只是命名分歧），先指出再决定是否执行；不扩展替代路线。

---

## §0 — Plan owner 已定裁定（最终决议，executor 直接按此实现）

### Tooltip 真源（不可改）

| 项 | 值 |
|---|---|
| Source file | `figma-data/normalized/components-tokenized/tooltips__1408_17152.json` |
| figmaName | `Tooltips` |
| nodeId | `1408:17152` |
| figmaPage | `— — Notifications & Pop box` |
| figmaPageId | `1379:4191` |
| figmaFileKey | `YbsPRUVmNdsbN40NNwh1Gn` |
| Type | `COMPONENT_SET` |
| 期望 variant 数 | **12**（2 darkTheme × 6 pointing） |

### Axes 裁定

按 figma variant 名（如 `'dark theme=on, pointing=left down'`）的**出现顺序**收集 axes，第一是 `dark theme`，第二是 `pointing`。

| figma axis | code prop | values（按 figma 出现顺序） |
|---|---|---|
| `dark theme` | `darkTheme` | `['on', 'off']` |
| `pointing` | `pointing` | `['left down', 'Center down', 'right down', 'left up', 'Center up', 'right up']` |

注意：figma axis 名含**空格**（`dark theme`）→ code prop 是 **camelCase**（`darkTheme`）。`pointing` 值的大小写**保 figma 原值**（`'Center down'` 是 PascalCase 词、`'left down'` 是 lowercase 词）——与 canonical Tooltip 的 `pointing` prop 类型完全对齐。

### Theme 字段裁定（按 prop-aliases.md GLOBAL alias 真源）

generator 必须给每个 variant 派生 `theme` 字段，按下表映射（**真源**：[`src/design-system/translation/prop-aliases.md`](../../../src/design-system/translation/prop-aliases.md) "项目级 GLOBAL axis alias / darkTheme ↔ theme" 段）：

| variant.props.darkTheme | variant.theme |
|---|---|
| `'on'` | `'dark'` |
| `'off'` | `'light'` |

⚠️ **反模式 #1 合规**：generator config 里 hardcode 这个 mapping **必须**在旁边加 `// TODO` 注释指向真源 `src/design-system/translation/prop-aliases.md` "darkTheme ↔ theme" 段——避免把项目级规则藏在脚本里。例如：

```js
// TODO: GLOBAL alias 真源在 src/design-system/translation/prop-aliases.md
//       「darkTheme ↔ theme」段；将来抽公共 module 时迁移
themeValueMap: { on: 'dark', off: 'light' },
```

⚠️ **不要**把 `theme` 放进 `axes` 数组——`axes` 是 prop 校验用，`theme` 是 filter metadata。两个字段同时存在：
- `variant.props.darkTheme`：运行时传给 canonical Tooltip
- `variant.theme`：grid 按 site theme filter 用 + α audit 入口

### Site theme 注入裁定

TooltipPage 给 `<FigmaMembersGrid>` 传 `:site-theme="'dark'"`（静态字面量，与 BadgePage 一致）——TVU 默认 dark mode（per memory dark-theme-only-monitoring）。这样 grid 仅渲染 6 个 dark variants（pointing × theme=dark）。

### TooltipPage 改造裁定

| 改 / 不改 | 内容 |
|---|---|
| **删** | `tooltipMembers` 手写数组、`figmaPage` / `figmaNodeIds` / "variant count=12" 字面量 |
| **改** | Figma Coverage 段：用 `<FigmaMembersGrid :members="tooltipFigmaMembers" :component="Tooltip" :site-theme="'dark'" />` 替手写 axes 段 |
| **保留** | Position Preview / Interaction Preview / Tooltip API 三段——这些是"开发者视角解释"段，类似 Badge 的 Tag/Type/Color 对照 |
| **改派生** | Position Preview 段的 `tooltipMembers` 改成 computed，从 `tooltipFigmaMembers.variants` filter 当前 site theme（dark）后取 pointing 列表；hover demo 仍用 `<Tooltip :dark-theme="activeTheme">` |
| **保 i18n** | `t()` bilingual handler 不动 |
| **不动** | `canonical/Tooltip.vue` / `Tooltip API` 表（plan §1.3 排除项 API 表） |

### Audit 配置裁定

`figma-sync/audit-page-t2-sample.mjs` 的 `PAGE_CONFIG` 加 `TooltipPage` 分支：

```js
TooltipPage: {
  component: 'Tooltip',
  membersFile: 'figma-data/normalized/docs-figma-members/tooltip.ts',
  pageFile: 'playground/docs/pages/TooltipPage.vue',
  gridFile: 'playground/docs/components/FigmaMembersGrid.vue',
  tokenFiles: [
    'src/canonical/Tooltip.vue',
    'playground/docs/pages/TooltipPage.vue',
    'playground/docs/components/FigmaMembersGrid.vue',
  ],
}
```

audit 算法**不动**——只扩配置数据。

### α audit 必须真正运行（不再 N/A）

Tooltip 有 theme axis → α audit 不再走 line 156-158 的 N/A 分支。期望 verdict = **pass**：
- regex 已修（[audit-page-t2-sample.mjs:172](../../../figma-sync/audit-page-t2-sample.mjs#L172) 在 commit f6e9a77 修过）能识别 `:site-theme="'dark'"`
- generator 输出 12 个 variant 都有 theme 字段（6 dark + 6 light）
- page 注入 `:site-theme="'dark'"` → grid filter 出 6 个 dark variant
- α 验证渲染的 variant.theme 全 = site theme = `'dark'` → pass

---

## §1 — 必读输入

按顺序读：

1. [`AGENTS.md`](../../../AGENTS.md) — 硬规则 #2 / #4 / #6
2. [`docs/meta-rules.md`](../../meta-rules.md) — 反模式 + 触发器 G
3. [`docs/internal/_plans/t2-sample-badge-plan.md`](../_plans/t2-sample-badge-plan.md) — **plan 真源**（schema 语义 / contract / audit verdict）
4. [`docs/internal/_plans/t2-sample-generator-output-schema.draft.md`](../_plans/t2-sample-generator-output-schema.draft.md) — generator 表达层定稿（已 commit f6e9a77）
5. [`docs/internal/_plans/t2-sample-grid-contract.draft.md`](../_plans/t2-sample-grid-contract.draft.md) — grid 表达层定稿
6. [`docs/internal/_plans/t2-sample-audit-impl.draft.md`](../_plans/t2-sample-audit-impl.draft.md) — audit 算法定稿
7. [`figma-data/normalized/docs-figma-members/types.ts`](../../../figma-data/normalized/docs-figma-members/types.ts) — schema 真源（**不动**）
8. [`figma-data/normalized/docs-figma-members/badge.ts`](../../../figma-data/normalized/docs-figma-members/badge.ts) — 参考 Badge generator 输出（你产出 tooltip.ts 应同结构）
9. [`figma-data/normalized/components-tokenized/tooltips__1408_17152.json`](../../../figma-data/normalized/components-tokenized/tooltips__1408_17152.json) — Tooltip figma 真源
10. [`src/design-system/translation/prop-aliases.md`](../../../src/design-system/translation/prop-aliases.md) — `darkTheme ↔ theme` GLOBAL alias 真源（**不动**，本轮只读）
11. [`src/canonical/Tooltip.vue`](../../../src/canonical/Tooltip.vue) — Tooltip canonical（**不动**）
12. [`playground/docs/pages/TooltipPage.vue`](../../../playground/docs/pages/TooltipPage.vue) — 待改造 page
13. [`playground/docs/pages/BadgePage.vue`](../../../playground/docs/pages/BadgePage.vue) — 已改造的范式参考
14. [`figma-sync/generate-docs-figma-members.mjs`](../../../figma-sync/generate-docs-figma-members.mjs) — 待扩 Tooltip 分支
15. [`figma-sync/audit-page-t2-sample.mjs`](../../../figma-sync/audit-page-t2-sample.mjs) — 待扩 PAGE_CONFIG.TooltipPage

---

## §2 — 任务清单

### 任务 2.1 — 扩 generator 加 Tooltip 分支

改 `figma-sync/generate-docs-figma-members.mjs`，在 `COMPONENTS` 加 Tooltip 分支：

- 沿用 Badge 风格——一份 config 描述 figma 真源 + propByAxis + 输出命名
- **新增能力**：表达 themeAxis 元数据让 generator 派生 `variant.theme` 字段。Plan owner 锁的是**含义**（按 §0 themeValueMap 派生），但 **executor 提议字段命名 + 嵌套结构**（如 `themeAxis: 'darkTheme'`、`themeValueMap: { on: 'dark', off: 'light' }`，或别的形态）。

`COMPONENTS.Tooltip` 必须能让 generator：
1. 解析 `dark theme=on, pointing=left down` 形态 variant 名（含空格的 axis 名）
2. axes 第一项是 darkTheme（按 figma 出现顺序）
3. 给每 variant 填 `theme: 'dark' | 'light'`（按 §0 mapping）
4. 输出 `figma-data/normalized/docs-figma-members/tooltip.ts`

`parseVariantName` 函数能否复用？看代码事实——variant 名 `'dark theme=on, pointing=left down'` 用 `.split(',')` 然后 `.split('=')` 应该能解析。验证再说。

CLI 用法不变：`node figma-sync/generate-docs-figma-members.mjs Tooltip`

### 任务 2.2 — 跑 generator 生成 tooltip.ts

```bash
node figma-sync/generate-docs-figma-members.mjs Tooltip
```

预期 `tooltip.ts` 含：
- `schemaVersion: 't2-sample-v0.1'`
- `component: 'Tooltip'`
- `source.figmaNodeId: '1408:17152'`
- `axes`: 2 项（darkTheme + pointing）
- `variants`: **12** 项，每项含 `props.darkTheme` + `props.pointing` + `theme` 字段
- `meta.variantCount: 12`
- export 类型 `TooltipFigmaProps` + const `tooltipFigmaMembers`

### 任务 2.3 — 改 TooltipPage.vue

按 §0 "TooltipPage 改造裁定" 表执行：

- 删 `tooltipMembers` 数组 + `figmaPage` / `figmaNodeIds` 字面量 + "variant count=12" 字面量
- import `tooltipFigmaMembers` 从 `@/figma-data/normalized/docs-figma-members/tooltip` 和 `TooltipFigmaProps` 类型
- import `FigmaMembersGrid from '../components/FigmaMembersGrid.vue'`
- Figma Coverage 段：删手写 `coverage-grid` chips → 用 `<FigmaMembersGrid :members="tooltipFigmaMembers" :component="Tooltip" :site-theme="'dark'" />`
- Position Preview 段：`tooltipMembers` 改成 `computed`，从 `tooltipFigmaMembers.variants` filter `theme === 'dark'`（dark mode）→ map 出 `{pointing, variantId}` 列表 → 渲染 6 卡片
  - 该 section 的卡片**不带** `data-figma-source="generator"`——这是手写区，γ audit 必须能区分（与 Badge Tag/Type/Color 三段同模式）
- Interaction Preview 段：基本不动，但如果引用 `activeTheme` 或类似 hardcode，可保留
- Tooltip API 表段：完全不动（API 表是 plan §1.3 排除项）
- 保 i18n `t()` 包装

### 任务 2.4 — 扩 audit PAGE_CONFIG

按 §0 audit 配置裁定，加 `TooltipPage` 分支到 `figma-sync/audit-page-t2-sample.mjs:10-22 PAGE_CONFIG`。

audit 算法（α/β/γ/δ 4 函数）**完全不改**——只是数据扩展。

### 任务 2.5 — 跑 audit + typecheck + 视觉验收

```bash
# typecheck
pnpm exec vue-tsc --noEmit

# 跑 Tooltip audit
node figma-sync/audit-page-t2-sample.mjs TooltipPage

# Badge audit baseline 重跑——**不应**有改变（regression check）
node figma-sync/audit-page-t2-sample.mjs BadgePage

# 视觉验收
pnpm dev
# 浏览器开 TooltipPage → 验证：
#   - Figma Coverage 段渲染 6 个 dark theme variants（不是 12，theme isolation 工作）
#   - 每个 cell 含 Tooltip 实例 + label "darkTheme=on, pointing=..."
#   - Position Preview / Interaction Preview / API 表完好
#   - dark theme 视觉无 regression
# 截图给 plan owner
```

预期 audit 4 verdict：
- **TooltipPage**: α=`pass` (真正运行) · β=`pass` · γ=`pass` · δ=`pass` · findings 全 0
- **BadgePage**: α=`N/A` · β=`pass` · γ=`pass` · δ=`pass` · findings 全 0（**与基线一致**）

如果 BadgePage 任一 verdict 偏离基线 → audit 算法被你改坏了 → 停下报告。

audit report 现在每个 page 一份，还是合并？看现状脚本——`PAGE_CONFIG[pageName]` 单 page 跑，写到固定路径 `docs/internal/t2-sample-audit-report.md`。每次跑覆写。

**裁定**：**改 audit 脚本**让 report 文件名按 page 区分，避免覆盖：
- `docs/internal/t2-sample-audit-report.<pageName>.md` 
- 如 `t2-sample-audit-report.BadgePage.md` / `t2-sample-audit-report.TooltipPage.md`
- 把现有 `t2-sample-audit-report.md` 移到 `t2-sample-audit-report.BadgePage.md`（git mv 等价：read 旧 + write 新 + 删旧；但因为没 commit ⚠️，不要 git mv，直接 fs 操作；最终留 dirty 状态，等审完一起 commit）

---

## §3 — 验收清单

executor 完成后必须自验：

- [ ] `tooltip.ts` 含 12 variants，每个 variant 有 `props.darkTheme` + `props.pointing` + `theme` 字段
- [ ] `tooltip.ts` axes 有 2 项（darkTheme `['on','off']` + pointing 6 values 按 figma 顺序）
- [ ] `tooltip.ts` 与 `badge.ts` schema 形态一致（types.ts 没改）
- [ ] TooltipPage.vue 删了所有手写 figma 字面量（`tooltipMembers` / `figmaPage` / `figmaNodeIds` / "variant count=12"）
- [ ] TooltipPage.vue 用 `<FigmaMembersGrid>` 替代 Figma Coverage 手写 chips
- [ ] Position Preview 段 `tooltipMembers` 派生自 generator（不再 hardcoded）
- [ ] `canonical/Tooltip.vue` / `prop-aliases.md` / `types.ts` / `badge.ts` / `BadgePage.vue` 均**不动**
- [ ] audit 算法 4 函数代码**不动**（只扩 PAGE_CONFIG + report 文件名分 page）
- [ ] `pnpm exec vue-tsc --noEmit` 0 错误
- [ ] TooltipPage audit: α=pass · β=pass · γ=pass · δ=pass · findings=0
- [ ] BadgePage audit baseline regression check：与 commit f6e9a77 时的报告 4 verdict 完全一致
- [ ] `pnpm dev` TooltipPage 视觉：Figma Coverage 段渲染 6 个 dark variants（不是 12），其它段完好
- [ ] 没 commit / 没 git add
- [ ] 没扩范围（不动 Select、不改 schema、不写新真源 .md）

---

## §4 — 完成报告（按下方格式回报）

```
## Tooltip 扩展轮 完成报告

### 改动文件
- figma-sync/generate-docs-figma-members.mjs (扩 Tooltip 分支, +XX 行)
- figma-data/normalized/docs-figma-members/tooltip.ts (生成产物, XX 行)
- playground/docs/pages/TooltipPage.vue (改 +XX/-XX 行)
- figma-sync/audit-page-t2-sample.mjs (扩 PAGE_CONFIG + report 路径分 page, +XX/-XX 行)
- docs/internal/t2-sample-audit-report.BadgePage.md (从原 t2-sample-audit-report.md 迁移)
- docs/internal/t2-sample-audit-report.TooltipPage.md (新增)
- docs/internal/t2-sample-audit-report.md 删除（仅迁移到 BadgePage 后清理）

### Generator config 表达层提议（plan owner 复审）
[贴出 COMPONENTS.Tooltip config 完整代码 + themeAxis/themeValueMap 字段命名提议 + 利弊]

### Tooltip audit 结果
- α theme isolation: <verdict> · evidence=<...> · 实际渲染 variant theme 集合=<...>
- β figma axis coverage: <verdict> · evidence=<...>
- γ runtime fabrication: <verdict> · evidence=<...>
- δ token purity: <verdict> · evidence=<...>

### Badge audit baseline regression check
- α=N/A · β=pass · γ=pass · δ=pass · findings=0 一致：[✓ / ✗ + 偏差描述]

### 视觉验收
- TooltipPage Figma Coverage 段实际渲染 variant 数量: <expect 6>
- 截图路径或描述: ...

### 验收 self-check
- [ ] tooltip.ts 12 variants × theme 字段
- [ ] tooltip.ts schema 形态对齐 badge.ts
- [ ] TooltipPage 删手写字面量 ✓
- [ ] canonical/Tooltip.vue 没动
- [ ] prop-aliases.md / types.ts / badge.ts / BadgePage.vue 没动
- [ ] audit 4 函数代码没动
- [ ] vue-tsc 0 错
- [ ] TooltipPage 4 verdict 全 pass
- [ ] BadgePage baseline 一致
- [ ] dev 6 dark variants 可见
- [ ] 没 commit
- [ ] 没扩范围

### 未解决项 / blocker
[如有，列出；无则写"无"]

STOP — 等 plan owner 复审 + 截图后给下一步指示（Select 扩展 或 milestone commit）。
```

---

## §5 — 严守约束总览

- ⚠️ **不要 commit / 不要 git add**——dirty 累积
- ⚠️ §0 9 项裁定**最终**，不再询问
- ⚠️ 不改 schema 主结构（`types.ts` 保持 commit f6e9a77 形态）
- ⚠️ 不改 audit 算法 4 函数（只扩配置）
- ⚠️ 不改 canonical Tooltip / Badge / prop-aliases.md / badge.ts / BadgePage.vue
- ⚠️ 不扩范围到 Select 或其它 page
- ⚠️ Audit baseline regression check：BadgePage 4 verdict 必须与 f6e9a77 commit 时一致
- ⚠️ Audit fail 不要自行"修到 pass"——回报 finding 让 plan owner 决定
- ⚠️ 完成 STOP，按 §4 格式回报