# Session Handoff

这份文档只做一件事：让新的 Session 用最短的提示词接上当前阶段，而不是重新复盘整段历史。

## 唤醒词

在新 Session 里，直接说这一句即可：

```text
继续 TVU handoff
```

## 收到唤醒词后的标准动作

新的 Session 必须按下面顺序执行：

1. 先阅读：
   - `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/docs/session-handoff.md`
   - `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/docs/multi-session-collaboration-rules.md`
   - `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/docs/figma-conformance-first.md`
   - `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/docs/conformance-issue-log.md`
   - `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/docs/generated-skeleton-promotion-plan.md`
   - `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/docs/site-pixel-parity-mechanism.md`
   - `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/docs/site-review-manifest.json`
   - `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/docs/figma-provenance-audit.md`
   - `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/docs/component-review-rules.md`

2. 先运行：
   - `pnpm audit:figma-conformance`
   - `pnpm audit:docs-site`

3. 先输出：
   - 读到的事实
   - 当前阻塞点
   - 本轮准备先修哪一层
   - 为什么这样排优先级
   - 本轮会更新哪些 `docs/` 文件

4. 在完成上面这些之前：
   - 不要继续批量生成新组件
   - 不要把 skeleton wrapper 当作完成组件
   - 不要把手写特例生成器继续扩散到其他组件

## 当前最新基线（2026-04-28）

- `pnpm audit:figma-conformance` ✅ `overallPass=true`
  - `skeletonGeneratedWrappers=0`
  - `publiclyExportedSkeletons=0`
  - `generatedIndexViolations=0`
- `pnpm audit:docs-site` ✅ `overallPass=true`，`errors=0`，`warnings=6`
  - `approvedComponentPages=17`
  - `inReviewComponentPages=5`
  - `blockedComponentPages=0`
  - 6 个 warnings：5 个 in-review 页面 + 1 个 IconPage foundation 资产展示口径
  - 严重程度口径已收紧（2026-04-28 commit `25f36e1`）：in-review 与 foundation source-type 不匹配降为 warn，其它（缺 baseline / 非 canonical / 非 figma-frame / source-type 不匹配）保持 error
- `pnpm audit:published-vs-code` ✅ `36 / 2 / 0 / 0`
  - `matched=36`
  - `figma-only=2`
  - `code-only=0`
  - `unmapped=0`
  - figma-only 2 项：`Popup Box` / `Chart`
- `pnpm test` ✅ `17 files / 105 tests`
- `pnpm build` ✅
- 5 个新加 docs page 当前 `pixelReviewStage=in-review`
  - `breadcrumb`
  - `form-item`
  - `prompt-message`
  - `steps`
  - `tabs`
  - 待人工核对与 Figma 的像素一致性
- Phase 6 进展：
  - `6.1` ✅
  - `6.2a` ✅
  - `6.2b` ✅
  - `6.3` ✅
  - `6.3.5` / `6.4` / `6.5` 待做

## 必守规则

### 图标体系

1. 所有普通语义图标统一通过共享 `Icon` 组件消费，不允许在运行时组件里直接内联 SVG 或直接引用 generated icon map。
2. 品牌资产与普通图标分开：
   - 普通图标走 `src/components/Icon/Icon.vue`
   - 品牌资产走 `src/components/Logo/Logo.vue`
3. 图标正式命名采用 `category/name`
   - 例如：`time/clock`
   - 旧别名仍可兼容，但新实现和新文档必须优先写 `category/name`
4. Figma 图标导出链当前会直接生成：
   - `manifest`
   - `generated/<category>.ts`
   - `loaders`
   - `esm/<category>.js`
   - `svg/<category>/<name>.svg`
5. 图标公共产物需要同时服务：
   - Vue 组件消费
   - React / TS 项目按分类导入
   - CDN 直接访问静态 SVG

### docs shell / 页面壳层

1. 顶部主题切换是全站级开关，不允许组件页自己再做一套局部主题切换器。
2. 语言切换、主题切换、版本记录等壳层能力属于站点壳层，不属于单个组件示例。
3. 页面入口 HTML 必须清掉默认白边，`html / body / #app` 不应再露出浏览器默认白色外边距。

### Tooltip 页面规则

1. `TooltipPage` 必须跟随网站全局主题，不允许页面内部再切 `dark / light`。
2. 审核页优先展示单一当前主题下的真实交互结果，而不是把两个主题同时并排铺开。
3. tooltip 预览优先采用 hover 触发，气泡应贴近 anchor，不能为了“全可见”而把气泡悬浮到很远的位置。

### 工作纪律

1. Codex 默认不修改 `figma-data/` tracked 文件；涉及清理、改 index、改 manifest，必须先 dry-run 再拿用户授权。
2. `pnpm sync:figma-library` 默认安全模式必须保持 `cleanup` 为 dry-run；只有显式 `--apply-cleanup` 才允许真实删除。
3. `audit:published-vs-code --auto-suggest-unmapped` 生成的新 mapping 条目，状态必须是 `needs-review`，不能自动 `approved`。
4. 所有关键结论必须回写 `docs/`，不能只留在对话里。
5. 多 Session / 多 Agent 并行时，必须遵守 `docs/multi-session-collaboration-rules.md`。

## 当前阶段（指向 PROJECT_GOAL）

当前在 Path B 路线图 `6.3 → 6.3.5 → 6.4 → 6.5 → npm 化 → Phase 7 文档站 → v0.1 上线` 之间。

完整路线图：`docs/internal/project-goal-roadmap-proposal-2026-04-28.md`

项目目标：`docs/PROJECT_GOAL.md`

## 当前阻塞点 / 待用户决策

- 决策点 1：`Popup Box / Chart` 进 `v0.1` 还是 `v0.2`
- 决策点 2：多角色视图是 `v0.1` 必备还是 `v0.1.x` 增强
- 决策点 3：`NP-1~5` 与 `7-A/B` 串行还是并行

## 下一步默认

进 `6.3.5` 反向 audit（验证 `src/canonical/` 无其它“自创未登记”项）。

## 历史方法论

阶段 `0–6` 的完整方法论沉淀见 `docs/internal/retrospection/2026-04-28-design-system-audit.md`。

`Button bridge` 演化、`4-22` 到 `4-24` 期间的样板链 narrative、`4-27` canonical expansion 的 `14` 组件清单等历史细节，可通过 `git log docs/session-handoff.md` 回溯。