# Next Session Pickup — code↔Figma 一致性验证（verification mode）

> 生成时间：2026-05-19
> 上次 session 结束状态：v0.6.0 ✅ published；v0.7.0 contrast cleanup 等设计师；v1.0 docs/scripts 全就位；STATUS / backlog slimmed
> **Session mode**：verification, **not build**。读完这份 pickup 后**禁止编辑组件源代码**（src/canonical/ src/components/ src/tokens/）。
>
> 起手第一句话：`按 docs/internal/_plans/next-session-pickup-2026-05-19-verification.md 验证 code↔Figma 一致性`

---

## 1. 为什么是 verification mode

v0.0 → v0.7 的"建设"工作已 organize 完。剩下只有：
- 设计师 review contrast → 改 Figma → sync 回 code（这一步不需要 dev 编辑 code）
- 抽样验证 code 是否 1:1 还原 Figma 样式（验证任务，**不是改东西**）
- 验证 audit pipeline 在 0 active findings 状态下持续稳定（防回归）

所以本 session 主要动作是：**跑 audit + 看 report + spot-check + 报告 finding**，不动 source。

---

## 2. 替代读取顺序（覆盖默认 5-step §3b/§4/§5）

| Step | 文件 | 作用 |
|---|---|---|
| 1 | [`docs/STATUS.md`](../../STATUS.md) | 知道当前 v0.6.0 published，v0.7.0 在等设计师 |
| 2 | [`docs/PROJECT_GOAL.md`](../../PROJECT_GOAL.md) §能力2 + §不要做 | 知道验证 bar：Figma URL → code 1:1 还原；不改 Figma |
| 3 | [`AGENTS.md`](../../../AGENTS.md) §硬规则 1/5/6 + §项目约束 | 知道：不修 Figma、差异必登记、用 canonical 不用 base、Figma plan 限制 |
| 4 | [`src/design-system/translation/`](../../../src/design-system/translation/) 四件套 | **已登记的 Figma↔Code 差异决定 = validation 的 ground truth** |
| 5 | [`docs/V1_RELEASE_CHECKLIST.md`](../../V1_RELEASE_CHECKLIST.md) | 已验证 vs 未验证清单 + 5 大决策 |
| 6 | [`docs/internal/a11y-contrast-report.md`](../a11y-contrast-report.md) 顶部统计 | 设计师手上现在在 review 什么 |
| 7 | 启动 docs site (`pnpm dev`) → [`/internal/a11y-report`](http://localhost:5173/internal/a11y-report) | 看活的 contrast 状态 |

跳过原 5-step 的：
- ~~step 3a tracker.md~~ — 排期 SoT，验证不需要
- ~~step 5 backlog entry~~ — 验证无 sprint entry

---

## 3. 验证工具索引

知道有这些就行，不必读全代码。每个都跑一次看 baseline。

```bash
# Library 内部一致性（应该全 green，回归 detector）
pnpm run prepublishOnly      # 13 audit gate 全跑（含下面的）
pnpm audit:figma-conformance     # figma↔code 一致性
pnpm audit:published-vs-code     # library publish vs code mapping (38 components / 642 icons)
pnpm audit:translation-completeness  # translation SoT 完整性
pnpm audit:design-system            # 设计系统级 audit
pnpm audit:tokenized-diff           # token diff report

# Mockup audit (consumer side)
pnpm audit:consumer-mockup --file <fileKey>           # I1/I2/I3 + C1/C2/C3
pnpm audit:consumer-mockup-binding <fileKey>          # M0/M1/M30
pnpm audit:consumer-code --dir <consumer-src-dir>      # R1/R2/R16

# a11y (运行需 `pnpm dev` 启动 server)
pnpm test:a11y                # axe Playwright 30 pages × 2 themes
node scripts/a11y-contrast-inspector.mjs   # 重新生成 text contrast report
pnpm audit:token-contrast    # static non-text contrast scan

# Figma URL → code lookup (能力 2 验证)
pnpm figma-url-to-canonical <figma-url>

# Visual regression (像素 baseline)
pnpm test:visual            # Playwright snapshot diff
```

---

## 4. 验证候选 sub-task 清单（按价值排）

### 优先级 1 — 跑全套 audit 看 baseline

```bash
pnpm run prepublishOnly 2>&1 | tee /tmp/audit-baseline.log
```

**预期**：13 个 gate 全 green。如果任一 fail → flag 给用户，这就是回归。

### 优先级 2 — spot-check Figma URL → code

抽 1-2 个组件做双向 trace：

```bash
# 假设组件 Button 的某个 variant
pnpm figma-url-to-canonical "https://www.figma.com/design/<file>/?node-id=337:12307"
# 输出 figmaName / codeNames / variantAxes / matched variant props
# 然后人工 cross-check src/canonical/ButtonBridge.vue 是否真有这 8 axis
```

候选抽样组件（覆盖 8-axis、dual-form、icon variants）：
- Button (8-axis canonical)
- FormItem (label dual-form)
- Tooltip (content dual-form)
- Pagination (variant + boolean props)
- Notification (multiple status)

### 优先级 3 — 看 published-vs-code audit 报告

```bash
cat docs/internal/published-vs-code-audit.md  # 38 components mapping
```

预期：✅ 38 matched · ❌ 0 figma-only · ⚠️ 0 code-only · ❓ 0 unmapped。任何非 0 → flag。

### 优先级 4 — 看 a11y report 活的状态

启动 docs site：
```bash
pnpm dev
# 浏览器: http://localhost:5173/internal/a11y-report
```

看：
- Text contrast：1998 violations / 104 unique pair（等设计师改 Figma 后会清零）
- Non-text contrast: 20 pairs（含 SAME VALUE 的）
- 设计师 review 进度（如果设计师已动手会反映在 Figma sync 后的 token 值上）

### 优先级 5 — visual regression baseline drift check

```bash
pnpm test:visual
# 应该全 pass。任何 diff → flag（要么 baseline 没更新，要么真回归）
```

---

## 5. 本 session **禁止做** 的事

| ❌ 不许 | 原因 |
|---|---|
| 编辑 src/canonical/* | 验证 mode，不动 code |
| 编辑 src/components/* | 同上 |
| 编辑 src/tokens/* | 等设计师从 Figma sync |
| `pnpm sync:figma-library` 写 figma-data/ | 等设计师 ack 在 Figma 改完 |
| 改 token-aliases.ts | translation SoT，是验证的 ground truth |
| 改 divergences-decisions.json | 同上 |
| bump 版本 | 等 contrast cleanup done 才 v0.7.0 |
| tag 任何 release | 同上 |

可以做：
- 跑各种 audit script
- 读 docs / 看 report
- 修 docs typo / 修 docs site 演示样式 bug（playground/docs/ 内）
- 报告 finding 给用户

---

## 6. 等的事 / 上游 dependency

| 上游 | 等的内容 | session 不动 |
|---|---|---|
| 设计师 | review [`a11y-contrast-report.md`](../a11y-contrast-report.md) → 改 Figma 24+ token | 是 |
| 用户 | 给新产品 repo 路径做 ESLint plugin reference adoption | 是 |
| 用户 | 决定哪些产品做 v1.0.0-rc.N 测试 | 是 |

如果用户在 session 中提供以上任一信息 → 转换 mode 处理（pickup 失效，按用户指令）。

---

## 7. 输出预期

session 结束应该有：

1. baseline audit log (`/tmp/audit-baseline.log` 或 commit 到 retrospect)
2. spot-check 报告（如有 finding）
3. STATUS.md 更新（"Last updated" 改今天）
4. 如发现 bug → backlog 加 entry（用 `pnpm new-backlog <PREFIX>` 拿 ID）

**不期望**：新 release、新 commit 改组件、新功能。