# Prompt — Phase X.4.2 Mass Refactor: 19 components canonical alignment to figma 真源

> **角色**：executor
> **范围**：按 plan owner 已写的 19 个 fix specs (`docs/internal/_prompts/x4-2-batch/<comp>-fix.md`) 改 canonical 实现 — spacing / color / typography / effect / composition / variant coverage 6 维度对齐 figma 真源
>
> ⚠️ **不要 commit / 不要 git add**——所有改动累积，user 视觉验收后一刀 commit
> ⚠️ 完成后 **STOP**，按 §4 格式回报；§4 必须含 §4.X 完整改动清单段
> ⚠️ **不扩范围**：只动 §0 列出的 canonical files + variables.css token 引用调整。**禁止**修改 generator / audit 脚本 / docs 文档 / prop-aliases.md / token-aliases.ts / icon-aliases.ts / figma-styles.json 等真源
> ⚠️ **typecheck / dev visual 失败 → STOP 报告**，不要自由发挥加 type cast 或绕过

---

## §0 — Plan owner 已定裁定（D1-D5 decisions + 新 token + revert）

### 已 落地（plan owner 完成，不需 Codex 动）

1. ✅ **D1 Notification light bg** — `--notification-bg-light` 改 `var(--color-grey-2)` (#f8f8f8) per figma 真源（之前 #ffffff 误设已 revert）
2. ✅ **D2 Progress canonical track** — `--progress-track-bg` 从 `var(--line-deep)` revert 回 `var(--bg-layer3)` (#262626) per figma 真源
3. ✅ **30+ 新 domain tokens** 加入 [`src/tokens/variables.css`](../../src/tokens/variables.css)：
   - **Theme-stable variant tokens**（用于 component 内部 theme variant，与 site theme 解耦）：
     - `--tooltip-bg-{dark,light}` / `-border-{dark,light}` / `-text-{dark,light}`
     - `--progress-track-bg-{dark,light}`
     - `--switch-bg-off-{dark,light}` / `-bg-disabled-off-{dark,light}`
   - **Domain structural tokens**:
     - `--pagination-{pagesize-selector-width,jumper-input-width,simple-nav-width}`
     - `--topbar-section-gap`, `--topbar-height-before-login`
     - `--prompt-message-{l-max-width,m-max-width}`
     - `--notification-{width-default,width-side-pop}`
     - `--tooltip-max-width`
     - `--checkbox-{size,radius}`, `--radio-{circle-size,circle-border-width,selected-dot-size}`
     - `--rating-star-size`
     - `--slider-{track-h-m,track-h-s,thumb-size-m,thumb-size-s,thumb-dot-radius-m,thumb-dot-radius-s}`
     - `--progress-{track-h-m,track-h-s,track-radius}`
     - `--badge-circle-size`
     - `--switch-{track-w,track-h,thumb-size,thumb-inset,thumb-travel}`
     - `--form-item-{row-height,textarea-min-height}`
     - `--input-number-{min-width,default-width,max-width}`
     - `--control-height-xxs` (cross-component)
4. ✅ **D5 Helvetica → Roboto** — backlog 加 `CANONICAL-008`（设计师 review，canonical 用 Roboto）

### 待你（executor）做（详见 §2）

5. **D3 TopBar slot rename**: canonical TopBar template 改 `<slot name="center">` → `<slot name="menu">`，`<slot name="right">` → `<slot name="right-content">`。检查 docs `playground/docs/pages/TopBarPage.vue` 等 consumers 是否有用旧 slot 名 → 同步改
6. **D4 darkTheme prop 保留 + axis alias** — Tooltip / CheckBox / Radio / Switch / Progress 不改 prop 名（保 `darkTheme: boolean`），但 CSS 改用新 theme-stable variant tokens（见 fix specs）
7. **19 components per-component 改造** 按各自 fix spec 文件

---

## §1 — 必读输入

按顺序：

1. [`AGENTS.md`](../../../AGENTS.md) — 硬规则
2. [`docs/meta-rules.md`](../../meta-rules.md) — 反模式 + 触发器
3. [`src/tokens/variables.css`](../../../src/tokens/variables.css) — 已加的 30+ 新 tokens（lines ~95+）
4. [`figma-data/normalized/figma-styles.json`](../../../figma-data/normalized/figma-styles.json) — figma 真源 7 Text Styles + 4 Effect Styles
5. [`src/design-system/translation/token-aliases.ts`](../../../src/design-system/translation/token-aliases.ts) — figma name ↔ canonical token alias
6. [`src/design-system/translation/prop-aliases.md`](../../../src/design-system/translation/prop-aliases.md) — Boolean / Slot / Composition aliases
7. [`src/design-system/translation/icon-aliases.ts`](../../../src/design-system/translation/icon-aliases.ts) — figma icon ↔ canonical icon
8. **19 fix specs**: [`docs/internal/_prompts/x4-2-batch/<comp>-fix.md`](../x4-2-batch/) — per-component 详细 mismatch + fix instruction + 提议 token

---

## §2 — 任务清单（19 components）

每个 component 按对应的 fix spec 文件改造。按 fix spec 中的 "Mismatches by dimension" 段处理 6 dimensions：

| Component | Fix spec 文件 | 主要工作类型 |
|---|---|---|
| **Pagination** | [`x4-2-batch/pagination-fix.md`](x4-2-batch/pagination-fix.md) | hierarchy refactor + spacing + composition |
| **Notification** | [`x4-2-batch/notification-fix.md`](x4-2-batch/notification-fix.md) | spacing + color + effect (`var(--shadow-l3)`) |
| **TopBar** | [`x4-2-batch/topbar-fix.md`](x4-2-batch/topbar-fix.md) | **slot rename (D3)** + spacing + add showMenu/showSearchBox props |
| **CheckBox** | [`x4-2-batch/checkbox-fix.md`](x4-2-batch/checkbox-fix.md) | theme-stable tokens + variant coverage (light theme) |
| **PromptMessage** | [`x4-2-batch/promptmessage-fix.md`](x4-2-batch/promptmessage-fix.md) | spacing + max-width tokens |
| **Slider** | [`x4-2-batch/slider-fix.md`](x4-2-batch/slider-fix.md) | typography + thumb-size tokens |
| **Badge** | [`x4-2-batch/badge-fix.md`](x4-2-batch/badge-fix.md) | radius + variant coverage (Filled/Line, Circle/Rectangle) |
| **Tooltip** | [`x4-2-batch/tooltip-fix.md`](x4-2-batch/tooltip-fix.md) | **theme-stable tokens** (bg/border/text) + effect (`var(--shadow-l3)`) |
| **Progress** | [`x4-2-batch/progress-fix.md`](x4-2-batch/progress-fix.md) | **theme-stable tokens** (track-bg-dark/light) + variant tokens |
| **Switch** | [`x4-2-batch/switch-fix.md`](x4-2-batch/switch-fix.md) | **theme-stable tokens** + variant coverage (off state) + size tokens |
| **Radio** | [`x4-2-batch/radio-fix.md`](x4-2-batch/radio-fix.md) | **theme-stable tokens** + circle dimension tokens |
| **Rating** | [`x4-2-batch/rating-fix.md`](x4-2-batch/rating-fix.md) | star size token + icon name alignment |
| **FormItem** | [`x4-2-batch/formitem-fix.md`](x4-2-batch/formitem-fix.md) | spacing + row-height token (partial — MCP cache incomplete, 已标 partial) |
| **InputNumber** | [`x4-2-batch/inputnumber-fix.md`](x4-2-batch/inputnumber-fix.md) | width tokens + Roboto font (D5) |
| **BreadcrumbItem** | [`x4-2-batch/breadcrumbitem-fix.md`](x4-2-batch/breadcrumbitem-fix.md) | padding + line-height + showSeparator prop |
| **TabItem** | [`x4-2-batch/tabitem-fix.md`](x4-2-batch/tabitem-fix.md) | variant coverage (Filled/Normal/White) + active bold |
| **TabList** | [`x4-2-batch/tablist-fix.md`](x4-2-batch/tablist-fix.md) | **major refactor**: delegate to `<TabItem>` 不 inline |
| **Table** | [`x4-2-batch/table-fix.md`](x4-2-batch/table-fix.md) | header bg + per-cell icon support (showLeftIcon/showRightIcon) + Roboto (D5) |
| **StepItem** | [`x4-2-batch/stepitem-fix.md`](x4-2-batch/stepitem-fix.md) | typography (`--text-style-body`/`--text-style-pop-title`) + icon name fixes + spacing |

### 任务 2.1 — 按 fix spec 改造 19 components

For each component, read the fix spec, apply changes to canonical Vue file (template + CSS scoped block).

**禁止**: 创新 token / 改 generator / 改 audit / 改 prop-aliases.md / 改 token-aliases.ts / 改 figma-styles.json / 改其他真源 .md。如果 fix spec 中标 "新 token 待 plan owner 确认" 但 plan owner 已加 (见 §0 token list)，正常使用 var(--xxx)。如果 fix spec 中提议的 token 在 §0 list 没出现，**STOP 报 blocker**。

### 任务 2.2 — TopBar slot rename consumers

Grep 全 repo for 旧 slot 名:
```bash
grep -rn 'name="center"\|#center\|name="right"\|#right' playground/ src/ 2>/dev/null
```
所有 TopBar 的 slot 用法同步更新（如果是别的组件用 name="center"/"right" 不动）。

### 任务 2.3 — typecheck

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

期望：0 错误。如果失败 → STOP 报 blocker（不要自由发挥 fix）。

### 任务 2.4 — alignment audit

```bash
node figma-sync/audit-canonical-figma-alignment.mjs
```

期望：findings 大幅下降（从当前 132 → 目标 < 30），8 error-severity (variant-coverage-missing) 应清空。

### 任务 2.5 — page audit baseline regression

```bash
node figma-sync/audit-page-t2-sample.mjs
```

期望：18 page audit reports 仅 timestamps 改动（page transform 已稳定）。

### 任务 2.6 — dev 启动等 plan owner 截图

```bash
pnpm dev
```

启动后 STOP 等 plan owner 截图确认。**executor 不自评 dev 视觉**。

---

## §3 — 验收清单

- [ ] 19 canonical components per fix spec 改造完成
- [ ] TopBar slot rename + consumers 同步改
- [ ] 没创新 token（所有 token 引用都在 §0 list 内）
- [ ] 没改 generator / audit / 真源 .md / prop-aliases / token-aliases / icon-aliases / figma-styles
- [ ] vue-tsc 0 错
- [ ] alignment audit findings 下降（变 < 30 + 0 error-severity）
- [ ] page audit baseline 仅 timestamps
- [ ] dev 启动等 plan owner 截图（不自评）
- [ ] 没 commit / 没 git add

---

## §4 — 完成报告

```
## Phase X.4.2 Mass Refactor 完成报告

### 改动文件 (按 fix specs 预期 scope)
- src/components/<19>/<X>.vue (per fix spec)
- src/canonical/TopBar.vue (slot rename if needed)
- playground/docs/pages/TopBarPage.vue 等 consumers (slot rename)

### §4.X 完整改动清单 (All M / A / D, 含 prompt 范围外)
[git status --short 全列表]
[如有范围外改动，标 ⚠️ 解释]

### Per-component 状态
- Pagination: ✓ done (X mismatches fixed) / ⚠️ partial (Y blockers) / ❌ blocked
- Notification: ...
- (19 components)

### typecheck
- vue-tsc: 0 错误 / X 错误（如失败 STOP）

### alignment audit
- Before mass refactor: 132 findings (8 error)
- After: <count> findings (<count> error)
- 显著下降项: <list>

### page audit baseline
- 18 reports timestamp-only OK / 偏离 (列出)

### dev 视觉
- pnpm dev 启动: OK
- 等 plan owner 截图（executor 不自评）

### 验收 self-check
- [ ] 19 components 改造
- [ ] TopBar slot rename + consumers
- [ ] 没创新 token
- [ ] 没改其他真源 .md
- [ ] vue-tsc 0 错
- [ ] audit findings 下降
- [ ] page audit baseline
- [ ] dev 启动等 plan owner
- [ ] 没 commit / 没 git add
- [ ] §4.X 完整改动清单已列

### 未解决项 / blocker
[fix specs 中的 blockers 处理结果，如:
- FormItem MCP cache incomplete → spec 已标 partial, 按 spec 已知部分改
- Default value drift (Badge color, Switch status) → 按 fix spec 推荐 align figma
- 其他 blocker if any]

STOP — 等 plan owner 复审 + 截图确认 → Phase X 全 commit (含 figma styles + audit upgrade + canonical mass refactor + codemod)。
```

---

## §5 — 严守约束总览

- ⚠️ **不要 commit / 不要 git add**
- ⚠️ §0 file 改动**精确按 19 fix specs scope** + variables.css 引用调整 (不改 token 定义) + TopBar consumers slot rename
- ⚠️ §4 完成报告**必须含 §4.X 完整改动清单段**
- ⚠️ dev 视觉**不自评**——启动 dev 后 STOP 等 plan owner 截图
- ⚠️ **没创新 token** — 所有引用必须在 §0 list 内 (variables.css 已加)，缺则 STOP 报 blocker
- ⚠️ **没改 generator / audit / 真源 .md** — 如需要改这些，STOP 报 blocker
- ⚠️ **typecheck 失败 → STOP 报告**，不要自由发挥
- ⚠️ 完成 STOP，按 §4 格式回报