# T4-Spike Badge Vertical Slice 测试说明

## 准备

- 在浏览器打开 Figma 文件，找到 Badge (`node-id=4821:1665`) 任一 variant，复制 URL。
- 准备 3 个独立 AI session（Claude / Cursor / Cline 任选）。
- 注意：当前包入口 `src/index.ts` 导出的 `Badge` 是 `src/canonical/Badge.vue`。旧 `src/components/Badge/Badge.vue` 仍存在，但不是本 spike 的 Figma bridge 目标。

## 测试 1：给 AI Code Connect 文件 + Figma URL

**输入**：

- 完整 `src/components/Badge/Badge.figma.ts` 内容
- `src/canonical/Badge.vue` 内容
- 一个 Badge Figma URL（如 `node-id=<某个 variant>`）

**指令**：

> 根据这个 Figma URL，给我生成对应的 Badge Vue 代码。

**期望输出**：

```vue
<Badge color="Green" tag="Filled" type="Circle">...</Badge>
```

具体 `color` / `tag` / `type` 必须跟 URL 所选 variant 的 Figma axes 一致。

**判 1:1**：手动比对 Figma variant axes ↔ AI 生成 props，全对 = pass。

## 测试 2：给 AI manifest + Figma URL

**输入**：

- `figma-data/normalized/ai-manifest.spike.json` 内容
- 一个 Badge Figma URL

**指令**：

> 用这份 manifest，根据 Figma URL 给我生成 Badge Vue 代码。

**期望**：同测试 1，生成当前 canonical Badge API：

```vue
<Badge color="Red" tag="Line" type="Rectangle">...</Badge>
```

## 测试 3：什么都不给（基线对照）

**输入**：

- 只给 Figma URL + 项目根路径

**指令**：

> 项目里有 Badge.vue，根据这个 Figma URL 生成对应代码。

**期望**：AI 自己摸出当前导出的 `Badge` 来自 `src/canonical/Badge.vue`，并生成 Figma axes 对应的 props。

这条是对照基线：

- 如果通过：说明 manifest / `.figma.ts` 在 Badge 这种简单组件上可能多余，需要重估 T4a/T4b 必要性。
- 如果不通过：说明 manifest / `.figma.ts` 真的有用，spike 验证项目目标可行。

## 判定矩阵

| 测试 | Pass = | Fail = |
|---|---|---|
| 1 | AI 生成代码 1:1 匹配 Figma axes | 不匹配 → `.figma.ts` 形态或输入说明有问题 |
| 2 | AI 生成代码 1:1 匹配 Figma axes | 不匹配 → manifest schema 不够 |
| 3 | AI 自己定位到 canonical Badge 并生成正确 props | AI 失败 → manifest / Code Connect 有真价值 |

## 给主 session 的反馈

请回传：

- 3 个测试的 pass / fail
- 每个测试输入的 Figma variant axes
- AI 实际生成的代码
- 1:1 是否达成
- 失败时缺了哪一层信息：Figma URL 解析、组件定位、prop 映射、还是 import 路径

---

## 实测反馈（2026-04-30 跑完 T4-spike）

测试用 Figma URL `node-id=4821-1660`（variant: Type=Circle, Color=Red, Tag=Filled, 文本"5"）。

### 测试结果

| 测试 | AI | 落点 | 输出 | 1:1 | 备注 |
|---|---|---|---|---|---|
| 1（给 .figma.ts + canonical/Badge.vue + URL） | Claude | canonical/Badge.vue | `<Badge color="Red" tag="Filled" type="Circle">5</Badge>` | ✅ PASS | 7 行属性级对照（bg/width/height/rounded/typography/padding）全对齐 |
| 1（同上） | Codex | canonical/Badge.vue | `<Badge color="Red" tag="Filled" type="Circle">5</Badge>` | ✅ PASS | 顺 src/index.ts 追到 canonical |
| 3（只给 URL + 项目根） | Claude | canonical/Badge.vue（凭 Badge legacy 顶部 LEGACY 警告注释引导） | 同上 | ✅ PASS | 警告注释起决定性作用 |

### 3 个关键发现（影响后续 T4 策略）

1. **Prop 值大小写真源是 PascalCase 不是 lowercase**
   - canonical/Badge.vue 定义 `color: 'Black' \| 'Blue' \| 'Green' \| 'Orange' \| 'Red'`（首字母大写）
   - Badge.figma.ts 已对（`Black: 'Black'`）；本 prompt 模板第 169 行示例曾写 lowercase（`Black: 'black'`），是模板 bug
   - **执行：** 后续类似 spike prompt 模板必须**先扫真源 .vue 类型定义**再写示例值，避免大小写假设
2. **legacy 警告注释 = 引导被测 AI 走 SoT 的关键机制**
   - 测试 3（什么都不给）能 pass 的根因：[src/components/Badge/Badge.vue](../../../src/components/Badge/Badge.vue) 顶部 `⚠️ LEGACY` 注释显式指向 canonical
   - 比 .figma.ts / manifest 更轻量，AI 在 Read tool 第一眼就能看到
   - **执行：** 任何"canonical 不 wrap legacy（rewrite 模式）"的组件都要加 LEGACY 警告注释。当前仓库只 Badge 一例（已加），其它 16 个 wrapper 组件不需要
3. **`.figma.ts` 在 1↔1 简单组件上对"AI 生成代码"可能多余，但对"Figma 同步"必须**
   - AI 生成视角：测试 3 已证简单组件无 .figma.ts 也能 pass
   - Figma 同步视角：Figma 设计师改了组件后，`figma connect` 命令能精确报告影响哪些代码文件——**没 .figma.ts 时只能全库 grep + 差异对比**
   - **执行：** `.figma.ts` 仍是 T4 必产物，不省。21 个组件全部要写

### 项目目标验证状态

| 目标 | 状态 |
|---|---|
| AI 拿 Figma URL → 1:1 还原 Vue 代码 | ✅ 端到端验证（Claude + Codex 双 AI 工具，对同一 URL 输出 1:1 一致） |
| 多 AI 工具消费收敛到 canonical SoT | ✅ legacy 警告注释 + divergences.md 登记起作用 |
| 项目协作规则可被 AI 工具消费 | ✅ Claude 自动识别"plan owner"角色 + 自动写 work-log |

---

## 第二轮验证（2026-04-30 加 AGENTS.md 硬规则 #6 后）

为验证"通用机制"是否对 wrapper 组件也有效（不只是 Badge 这种孤立特例），加 AGENTS.md 硬规则 #6 后挑 **Tooltip**（wrapper 模式，canonical 跟 base API 错位明显）测试。

### 测试输入

新 Claude session，仅给：
```
根据这个 Figma URL 生成对应的 Tooltip Vue 代码：
https://www.figma.com/design/.../node-id=1408-17135
```

### Claude 行为（端到端 PASS）

1. 自动加载 figma-implement-design skill
2. 第一步读 [AGENTS.md](../../../AGENTS.md) + [retrospection 2026-04-30](../retrospection/2026-04-30-t4-spike-validated.md)（项目协作规则吸收）
3. **显式引用 "Per 项目硬规则 #6, 从 Figma URL 生成 Vue 代码必须以 src/canonical/* 为 SoT"**——按 number 引用规则
4. 抓 Figma 上下文（get_design_context / screenshot / variable_defs / **code_connect_map**）
5. 读 [src/canonical/Tooltip.vue](../../../src/canonical/Tooltip.vue) + [divergences.md](../../../src/design-system/translation/divergences.md)
6. 输出 7 行属性级对照表 + Vue 代码：

```vue
<Tooltip dark-theme="on" pointing="left down" content="Description">
  <button>Hover me</button>
</Tooltip>
```

7. **自验清单同时引用 #2 / #3 / #4 / #5 / #6 五条硬规则做合规性检查**

### 关键发现

**通用机制 PASS**——AGENTS.md 硬规则 #6 + 必读链路是充分的；不需要给 17 wrapper base 文件加 header（按反模式 #2"不打补丁"）。

### 副作用：Code Connect publish 的 Pro plan 限制

测试 4 步抓 `get_code_connect_map` 时返回：

> **"You need a Developer seat in an Organization or Enterprise plan to access Code Connect."**

意味着 `figma connect publish` 需要 Organization / Enterprise 计划，**Pro plan 不可达**。

### 影响 T4 batch 决策

| 价值 | Pro plan 可达？ | 当前已落地？ |
|---|---|---|
| AI 拿 Figma URL → 1:1 还原 Vue 代码 | ✅ | ✅（rule #6 + canonical + divergences） |
| 多 AI 工具收敛到 canonical SoT | ✅ | ✅（rule #6 + Badge legacy header） |
| Figma 改 → 现有 audit 报告 drift | ✅ | ✅（`pnpm sync:figma-library`） |
| `figma connect publish` 把 .figma.ts 推到 Figma DevMode | ❌（需 Org/Ent seat） | — |
| DevMode 面板显示代码片段 | ❌（依赖 publish） | — |

**决策**：T4 batch（写 20 个 .figma.ts）**DEFERRED until Org upgrade**。Pro tier 上 Bridge 主价值已通过 rule #6 + canonical SoT 拿到；写更多 .figma.ts 只是 Org-tier 投机价值。

下一步：**T2 / T3**（docs site + EP 风格分类，开发者实际拿到的价值）。

详见 [retrospection 2026-04-30 阶段 6](../retrospection/2026-04-30-t4-spike-validated.md)。