# Codex Prompt: T1b 头号任务 — 迁 darkTheme↔theme 全局别名到 prop-aliases.md

> **本 prompt 在新 Session 中执行**——你（executor）没有之前对话的上下文。所有需要的输入都在仓库文件里，按下面"必读前置"读完。
>
> **任务性质**：纯执行——把硬编码在 audit 脚本里的项目级别名迁到翻译层真源（`prop-aliases.md`），改 audit 脚本从真源读，删硬编码 + 删 TODO 注释。**没有任何抽象设计任务**——alias 内容已 plan owner 在 axis-implementation-map.md 真源里写明。

---

## 必读前置（按顺序，不能跳）

新 Session 必须先读全：

1. **`AGENTS.md`** — 项目级 AI 协作入口（看 executor 角色行为约束）
2. **`docs/meta-rules.md`** — 元规则真源（看反模式清单 + 触发器 G + 触发器 I + 实证沉淀附录）
3. **`src/design-system/translation/prop-aliases.md`** — 翻译层真源（**本轮要追加 1 条 alias 登记**）
4. **`src/design-system/translation/divergences.md`** — 翻译层真源（参考已登记的 Class B 5 组件 darkTheme 段，line 81-87 附近）
5. **`src/design-system/translation/axis-implementation-map.md`** — Axis 实现层级真源（看 Instance 2 / 7 / 8 / 9 关于 SelectBoxLine.feature；本轮**不动它**）
6. **`figma-sync/audit-component-token-fidelity.mjs`** — Round 3 v2 audit 脚本（含硬编码 `GLOBAL_AXIS_ALIASES` + `// TODO(T1b)` 注释；本轮要清理）
7. **`docs/internal/component-token-fidelity-report.md`** — Round 3 v2 报告（用于跑前对比基线）
8. **`figma-data/normalized/component-token-fidelity.audit.json`** — Round 3 v2 机读 JSON

读完前不要写任何代码。

---

## 上下文：为什么有这个任务

audit 脚本当前在 `GLOBAL_AXIS_ALIASES` 常量里硬编码了一条**项目级真源约定**：

```js
// figma-sync/audit-component-token-fidelity.mjs (脚本里硬编码)
const GLOBAL_AXIS_ALIASES = {
  axisName: { 'dark theme': 'theme', darkTheme: 'theme' },
  axisValue: {
    theme: { on: 'dark', off: 'light' },
  },
}
// TODO(T1b): 移到 src/design-system/translation/prop-aliases.md 后从文件读
```

这违反 **meta-rules 反模式 #1**："项目级规则不在脚本里硬编码，应在 .md 真源，工具读真源"。

T1a 修补阶段（v1 / v1.5 fix patch）权宜硬编码并留 TODO；T1b 头号任务就是把它迁到真源。

**真源应该是 `prop-aliases.md`**——它已经登记了 41 行级别的项目命名 alias，是这条 alias 的天然归属。

---

## 你的角色边界（meta-rules 触发器 G）

| 已定（plan owner 真源，不要改 / 不要重新设计） | 你要做（执行） |
|---|---|
| alias 内容（darkTheme=on/off ↔ theme=dark/light） | 按已定内容追加到 prop-aliases.md |
| axis-implementation-map.md schema / enum / 16 instances | 不动 |
| Plan v2 全部内容 | 不动 |
| 其它 verdict 类型 / evidenceLevel schema | 不动 |
| Round 3 v2 audit 脚本骨架（5 个 verify\*() / Vue AST / palette resolver / 等） | 不动 |

**严禁做的事**：

- ❌ 改 `axis-implementation-map.md` 任何内容
- ❌ 改 `docs/internal/_plans/t1a-fix-v2-plan.md`（已批准）
- ❌ 改 `docs/meta-rules.md`（元规则真源）
- ❌ 加新 verdict 类型
- ❌ 改其它 src/* 代码（T1b 头号只动翻译层，不动组件代码）
- ❌ 改其它 figma-sync/*.mjs（除 `audit-component-token-fidelity.mjs`）
- ❌ git add / git commit / git push（**M1 还远，本任务严格 no-commit**）

---

## 任务 1：在 `src/design-system/translation/prop-aliases.md` 追加 alias 登记

**输入**（plan owner 已定）：alias 内容如下，参照现有 prop-aliases.md 表格格式追加：

```
figma 真源命名: darkTheme (axis) / dark theme (axis 别写法)
canonical 真源命名: theme

axis name 映射：
  - 'dark theme' → 'theme'
  - 'darkTheme' → 'theme'

axis value 映射（在 theme axis 下）：
  - 'on' → 'dark'
  - 'off' → 'light'

适用范围：所有组件（项目级 GLOBAL alias）。当前涉及：
  - Tooltip（runtime 层暴露 theme prop，canonical 层用 darkTheme）
  - Class B 5 组件：Input / CheckBox / Radio / Switch / Select
    （canonical 层用 darkTheme prop，runtime 层不暴露 theme，
     由站点 ThemeProvider + CSS 变量驱动）

来源：v2 plan T1b 头号任务（用户 2026-04-29 confirmed 全局规则）
relevant：figma-sync/audit-component-token-fidelity.mjs 之前在
GLOBAL_AXIS_ALIASES 常量里硬编码本条；T1b 头号迁到本文件作为真源，
audit 脚本改从本文件读。
```

**追加位置**：登记到 prop-aliases.md 现有表格的合适位置（保持表格格式一致）；如果现有表格 schema 不能直接表达 axis name + axis value 的二维映射，**在 prop-aliases.md 末尾另起一段 "## 项目级 GLOBAL axis alias"**，用 markdown 列表格式写：

```markdown
## 项目级 GLOBAL axis alias（影响所有组件）

### darkTheme ↔ theme

- **figma axis 名 → canonical axis 名**：
  - `dark theme` → `theme`
  - `darkTheme` → `theme`
- **theme axis 值映射**：
  - `on` → `dark`
  - `off` → `light`
- **适用范围**：所有组件（GLOBAL）。当前已识别：Tooltip / Input / CheckBox / Radio / Switch / Select
- **历史**：T1a 修补阶段在 audit 脚本 `GLOBAL_AXIS_ALIASES` 常量里硬编码；T1b 头号任务（2026-04-29）迁到本文件作为真源，audit 脚本读本文件
```

**严格按真源单一原则**：alias 内容**只写在 prop-aliases.md**，不在脚本 / 其它 .md 复制。

---

## 任务 2：改 audit 脚本从 prop-aliases.md 读 alias

**输入**（plan owner 已定真源解析方式）：

audit 脚本现状：

```js
// figma-sync/audit-component-token-fidelity.mjs
const GLOBAL_AXIS_ALIASES = { /* 硬编码内容 */ }
// TODO(T1b): 移到 prop-aliases.md 后从文件读
```

**你要做**：

1. 实现 `loadAxisAliasesFromPropAliasesMd()` 函数
   - 输入：`src/design-system/translation/prop-aliases.md` 文件路径
   - 输出：与原 `GLOBAL_AXIS_ALIASES` 同 shape 的对象 `{ axisName: {...}, axisValue: {...} }`
   - 解析方式：找 `## 项目级 GLOBAL axis alias` 段，按 markdown 列表提取（参考任务 1 写入的格式）
   - 健壮性：如果 prop-aliases.md 解析失败（文件不存在 / 段缺失 / 格式异常），抛清晰错误（不静默兜底硬编码——按 meta-rules 反模式 #1，硬编码不应再存在）

2. 替换硬编码：
   - 删除 `const GLOBAL_AXIS_ALIASES = { ... }` 常量定义
   - 删除 `// TODO(T1b): ...` 注释
   - 在脚本启动时调用 `loadAxisAliasesFromPropAliasesMd()` 并赋值给运行时常量
   - 后续所有用到 `GLOBAL_AXIS_ALIASES` 的地方保持 API 不变（运行时常量名可以保留 `GLOBAL_AXIS_ALIASES`，只是来源从硬编码变为加载）

3. 不动现有 audit 算法的其它任何部分。

**预期效果**：脚本不再含任何项目级 alias 硬编码；alias 真源唯一在 prop-aliases.md。

---

## 任务 3：重跑 audit 验证（按 meta-rules 触发器 I 三层核对）

```bash
# 第 1 跑
node figma-sync/audit-component-token-fidelity.mjs

# 第 2 跑（验证幂等）
node figma-sync/audit-component-token-fidelity.mjs
```

**Sanity check**（按 meta-rules 触发器 I：JSON 真源 + 渲染层 + grep 三层核对）：

| # | 检查项 | 期望 | 验证命令 |
|---|---|---|---|
| 1 | HEAD 不动 | `c9032ad` 之后是 `cf62996` 和 `ccf48a0`（最近 commit），本任务**不应**新增 commit | `git log --oneline -3` |
| 2 | prop-aliases.md 含新 alias | "项目级 GLOBAL axis alias" 段存在 | `grep -n "项目级 GLOBAL axis alias" src/design-system/translation/prop-aliases.md` |
| 3 | audit 脚本不再硬编码 alias | grep 应为 0 | `grep -c "axisName: { 'dark theme'" figma-sync/audit-component-token-fidelity.mjs` 应为 0 |
| 4 | audit 脚本不再含 TODO(T1b) | grep 应为 0 | `grep -c "TODO(T1b)" figma-sync/audit-component-token-fidelity.mjs` 应为 0 |
| 5 | audit 脚本含新加载函数 | grep 应 ≥ 1 | `grep -c "loadAxisAliasesFromPropAliasesMd\|loadAliasesFromPropAliases" figma-sync/audit-component-token-fidelity.mjs` |
| 6 | 脚本幂等 | 跑两次后 git diff 报告仅时间戳差 | `git diff docs/internal/component-token-fidelity-report.md \| wc -l` 应很小 |
| 7 | Tooltip 段 axes 仍含 `theme [dark\|light]`（用 JSON 真源） | true | `node -e "const d=JSON.parse(require('fs').readFileSync('figma-data/normalized/component-token-fidelity.audit.json','utf8'));const t=d.components.find(c=>c.componentName==='Tooltip');console.log(t.axes)"` 输出应含 `theme: [...'dark', 'light'...]` |
| 8 | Tooltip 段 token-match-via-custom-property-chain 数（用 JSON 真源） | 跟 Round 3 v2 大致相同（轻微波动可接受） | `node -e "const d=JSON.parse(...);const t=d.components.find(c=>c.componentName==='Tooltip');const f=t.variants.flatMap(v=>v.findings);console.log(f.filter(x=>x.verdict.includes('custom-property-chain')).length)"` |
| 9 | 总 finding 数（用 Summary） | 36089 ± 50（极小变化） | `head -25 docs/internal/component-token-fidelity-report.md` 看 Summary |
| 10 | 改的文件只有 2 个 | `src/design-system/translation/prop-aliases.md` + `figma-sync/audit-component-token-fidelity.mjs`（+ 报告/JSON 自动重生成） | `git status --short` |

**注意触发器 I**：任何"X 是否存在"的判断**先用 JSON 真源核查**（`node -e "JSON.parse(...)..."`）。grep 命令是辅助验证，不是诊断结论。

如果某项 sanity 不通过 → 不要硬调代码对上数字。先报告原因，让 plan owner 复审。

---

## 任务 4：⚠️ 不要 commit

```
❌ git add
❌ git commit
❌ git push
❌ git stash
```

按 v2 plan 工作纪律 1 修订版（plan owner 拆细）：
- 真源升级（prop-aliases.md）+ audit 实施层产物 → 由 plan owner 复审后决定 commit 时机
- executor 跑完留 dirty，**不自己 commit**

允许新增 / 修改：

- ✅ `src/design-system/translation/prop-aliases.md`（追加 alias 段）
- ✅ `figma-sync/audit-component-token-fidelity.mjs`（迁硬编码 + 删 TODO + 加 loader）
- ✅ `docs/internal/component-token-fidelity-report.md`（自动重生成）
- ✅ `figma-data/normalized/component-token-fidelity.audit.json`（自动重生成）

---

## 任务 5：完成后 STOP + 报告关键数字

```
任务 1 prop-aliases.md 追加：
  ✅ 已写入"项目级 GLOBAL axis alias"段
  追加行数：N

任务 2 audit 脚本迁移：
  ✅ 硬编码 GLOBAL_AXIS_ALIASES 常量定义已删除
  ✅ TODO(T1b) 注释已删除
  ✅ loadAxisAliasesFromPropAliasesMd 函数已实现
  解析行为：✅ 解析成功 / ❌ 失败时抛错（不兜底硬编码）

任务 3 重跑 + Sanity check（10 项）：
  通过：N / 10
  未通过：[列出来 + 原因]

audit 报告关键数字（vs Round 3 v2）：
  总 finding：N（vs 36089）
  Tooltip token-match-via-custom-property-chain：N（vs 12）
  token-match-via-prop：N（vs 72）
  其它 verdict 主要变化：[如有]

工作区状态：
  modified: 2（prop-aliases.md + audit 脚本）
  untracked: 2-3（报告/JSON 是 modified 还是 untracked 视情况）
  HEAD: 应仍 ccf48a0
```

**STOP。不要进 T1b 后续刀。不要 commit。**

---

## 给 executor 的元提醒（meta-rules 触发器 G + I 反向兜底）

新 Session 执行时如果发现：

- prompt 让你"**设计 alias 内容**" / "**决定哪些组件适用**" / "**选定 prop-aliases.md 的 schema 扩展**" → **这是 plan owner 漏写了真源**，**报告给 plan owner**，不要自己设计
- prop-aliases.md 现有格式跟 alias 内容不兼容 → **不要自己改格式**，在任务 1 用"另起 ## 项目级 GLOBAL axis alias 段"方案（已写在任务 1 里），把判断报告给 plan owner
- audit 脚本里 GLOBAL_AXIS_ALIASES 用法多于一处 → 报告所有用法位置，不要自己重构
- sanity check 跑完报告变化大于预期（如 finding 数变 1000+）→ **报告原因**，不要"修代码让数字对上"

按 meta-rules 触发器 I：所有"X 是否存在"判断**先 JSON 真源核查**，不只 grep。

完成后 STOP。