# Cleanup — docs site hex literals → var(--token)

> **触发方式**：用户对 executor 说 `请按 docs/internal/_prompts/cleanup-docs-site-hex-to-tokens.prompt.md 执行`
>
> **角色**：executor (Codex)
> **Plan owner**：Claude Code（出 prompt + 审 diff）
> **Mode**：surgical cleanup —— **只改 `playground/docs/**`，不动 `src/**`**
> **STOP**：完成后报告 diff + 跑 `pnpm audit:design-system` + `pnpm test:a11y` 看回归

---

## 1. 起因

2026-05-19 a11y-contrast-report 加 scope 分类后实测：

| Scope | Failing nodes | Owner |
|---|---:|---|
| library | 196 | 设计师（改 Figma token 或组件 token 引用） |
| **docs-chrome** | **479** | **本任务清理** |
| **demo-local** | **1322** | **本任务清理** |

`playground/docs/` 内有 ~37 行 hex / rgb 字面量，这些不该存在——docs site 也应该用 design system tokens 演示，而不是自己写 hex。

## 2. 静态扫描已知 hot-spot

跑 `grep -rEn '#[0-9a-fA-F]{3,8}\b|rgb[a]?\(|hsl[a]?\(' playground/docs/ --include='*.vue' --include='*.ts' --include='*.css'` 得到 37 命中。分三类：

### 2.1 真 bug——直接改成 var(--token)
| 文件 | 行 | 问题 | 建议 token |
|---|---|---|---|
| `playground/docs/pages/TopBarPage.vue` | 383-384 | `background: #4c46d6; color: #fff;` demo 自调颜色 | 用 `--brand` / `--color-white` 或换 `<Button>` |
| `playground/docs/pages/SliderPage.vue` | 253-254 | `background: #1b1b1b; border-color: rgba(255,255,255,0.08)` | `--bg-layer1` (dark) / `--line-light` |
| `playground/docs/pages/A11yReportPage.vue` | 443-475 | code block / pill bg 一堆 hex | `--bg-layer2/3`、`--text-body`、`--red-bg` / `--orange-bg` / 等 |
| `playground/docs/docs.css` | 197 | `box-shadow rgb(0 0 0 / 18%)` | `--shadow-*` token 或新建 |
| `playground/docs/pages/ButtonPage.vue` | 1029-1030 | gradient `rgba(0,0,0,0.15)` demo | `--shadow-*` 或 `--line-light` |

### 2.2 合法 raw hex——保留 + 加注释
| 文件 | 行 | 合法理由 |
|---|---|---|
| `playground/docs/pages/atomicAssets.ts` | 409+ | 颜色文档页的 swatch 表，**就是要展示 raw 值** |
| `playground/docs/pages/ColorPage.vue` | 561-562 | `rgb(from currentColor r g b / 0.08)` modern CSS color-mix 用法，不是 hex |
| `playground/docs/pages/ChartPage.vue` | 141-146 | chart palette **需要** raw hex 数组传给 chart lib（如果 token 化等设计师定 `--chart-palette-*`） |

### 2.3 灰色地带——讨论后决定
| 文件 | 行 | 状态 |
|---|---|---|
| `playground/docs/pages/A11yReportPage.vue` | 154 | placeholder 文案 `e.g. --text-2 or #434343`，是 UI 文本不是样式 → 保留 |

## 3. 任务

### 3.1 改 2.1 类（~10 处）
- 优先用 `src/tokens/variables.css` 已有 token，**不新建 token**
- 没有合适 token 的，留 hex 但加 `/* TODO: needs token */` 注释，并在最终报告里列出来

### 3.2 处理 2.2 类
- 在每个文件顶部 / 相关段加 1 行注释说明"此处 hex 是 design system 展示物，故意保留"
- 例如 `atomicAssets.ts`：注释 `// Raw swatches for color documentation — hex values are the source data, do not tokenize.`

### 3.3 跑 axe 重测
- `pnpm dev` 起服务后 `pnpm exec node scripts/a11y-contrast-inspector.mjs` 重跑
- 看 scope=`docs-chrome` 和 scope=`demo-local` 的 nodeCount 是否显著下降
- 期望：从 479 + 1322 = 1801 降到 ≤ 500（剩下都是 raw swatch / placeholder 等合法保留）

### 3.4 跑 audit:design-system 验证库 surface 没误触
- `pnpm audit:design-system` 必须保持 0 hardcoded color in `src/components/`
- 如果误改了 `src/`，立刻 revert

## 4. STOP 协议

完成后：
1. `git diff --stat playground/docs/` — 列改了哪些文件
2. `pnpm audit:design-system` 输出
3. `pnpm exec node scripts/a11y-contrast-inspector.mjs` 后 scope 表（library / docs-chrome / demo-local）
4. 列 2.1 类里**没找到合适 token** 的 hex（TODO 列表）
5. STOP，等 plan owner 复审

**禁止做的事**：
- ❌ 改 `src/canonical/*` / `src/components/*` / `src/tokens/*`（这是 library SoT）
- ❌ 改 `scripts/a11y-contrast-inspector.mjs`（只跑它，不改）
- ❌ 改 Figma 真源数据 `figma-data/**`
- ❌ commit 或 push（plan owner 复审后由用户拍板 commit）
- ❌ 自创 token——发现 token 缺失时只能 TODO 标记，等用户 + 设计师拍板新 token

## 5. 输出物清单

- `playground/docs/**` 改动 diff
- 重跑后的 `docs/internal/a11y-contrast-report.md`（scope 表 nodeCount 下降）
- 重跑后的 `playground/docs/data/a11y-contrast-report.json`
- STOP 报告含 4 条上面那些信息 + TODO 列表

---

**完成后 STOP，等 plan owner 决定下一步**。