# Tier 1-A Sprint 1 — axis-implementation-map.md → JSON + Schema > **触发方式**：用户对 executor 说 `请按 docs/internal/_prompts/tier1a-sprint1-axis-impl-json.prompt.md 执行` > **角色**：executor > **依赖**：[`docs/internal/_plans/tier1a-translation-schema-spec.md`](../_plans/tier1a-translation-schema-spec.md)（必读 §0-3, §6 D1-D6 决议 = 全推荐通过） > **完成后 STOP**，列改动 + 未解决项给 plan owner 复审 --- ## 0. 起手 Pre-flight check（mandatory 顺序） ```bash git status --short # 应只有别 session dirty（.claude/, AGENTS.md, docs/STATUS.md），不应含 src/design-system/translation/ 或 docs/internal/ pnpm test # 应 105 passed | 1 skipped pnpm exec vue-tsc --noEmit # 应 0 错 pnpm audit:figma-conformance # baseline 通过状态 ``` 任一不绿 → **STOP**，报告，不要硬上。 --- ## 1. 任务摘要 把 [`src/design-system/translation/axis-implementation-map.md`](../../../src/design-system/translation/axis-implementation-map.md) 的 16 个 instance 转为 JSON + JSON Schema。这是 Tier 1-A 4-sprint 拆解的 sprint 1（最简单），目的： - 验证 spec §0 的"split 路径"在最 schema-ready 文件上跑通 - baseline 实跑后 plan owner calibrate sprint 2-4 估时 - **不动 audit 脚本**（grep 实证 audit-*.mjs 0 引用 axis-implementation-map） **严格范围**：仅本文件（axis-implementation-map.md）+ 3 处活跃 docs 引用。其它 translation/ 文件不动（sprint 2-4 处理）。 --- ## 2. 任务输入 源文件：[`src/design-system/translation/axis-implementation-map.md`](../../../src/design-system/translation/axis-implementation-map.md) 需要抽取的 instance：md 章节 4 的 16 个 `### Instance N: ...` 段（Instance 1 ~ 16，全部 read 整文件保 fidelity）。 **Schema 字段已定义在 md 章节 3**： | 字段 | 必填 | 类型 | |---|---|---| | `figmaComponent` | ✓ | string | | `figmaComponentSetIds` | ✓ | string[]，每项 pattern `^[0-9]+:[0-9]+$` | | `figmaAxis` | ✓ | string | | `figmaValue` | ✓ | string \| `*` | | `codeImplementationLayer` | ✓ | enum 5 值（见下） | | `codeFile` | ✓ | string \| string[] | | `codeAnchor` | ✓ | string | | `verifyHint` | 推荐 | string | | `notes` | 可选 | string | **新增字段**（spec 加）： - `id`: string，kebab-case，每条 instance 唯一（pattern `^[a-z0-9-]+$`），由 executor 按 `--` 命名（如 Instance 1 → `button-color-palette`，Instance 2 → `selectboxline-feature-date`） **enum** `codeImplementationLayer` 允许值： - `css-class` - `vue-prop` - `vue-computed-palette` - `css-custom-property-chain` - `cross-component-topology` --- ## 3. 任务输出（3 个 deliverable） ### Deliverable 1 — 新 JSON 数据文件 **路径**：`src/design-system/translation/axis-implementation-map.json` **结构**（spec §2.1 草案）： ```json { "$schema": "./schemas/axis-implementation-map.schema.json", "version": 1, "instances": [ { "id": "button-color-palette", "figmaComponent": "Button", "figmaComponentSetIds": ["1545:51854", "1545:51964", "1545:57246", "1545:57247", "1545:47446", "1545:47447", "1545:51851", "1545:51852"], "figmaAxis": "color", "figmaValue": "*", "codeImplementationLayer": "vue-computed-palette", "codeFile": ["src/components/Button/Button.vue"], "codeAnchor": "palette computed: 262 / buttonVars computed: 365 / indirect vars used in CSS: --btn-bg (line 458) / --btn-color (line 459) / --btn-border (line 457)", "verifyHint": "grep -n \"const palette\\|const buttonVars\" src/components/Button/Button.vue", "notes": "palette 按 props (color, status, theme, style) 输入算出 --brand / --brand-hover / --red / --red-hover 等真实 token；audit 验证时需解析 Vue AST 找 palette ObjectExpression，按当前 variant 的 axis tuple 在 palette 分支里查最终 cssVar，再跟 figma cssVar 比对" }, ... ] } ``` **fidelity 要求**： - 16 instance 全转，**1:1** 保 md 内容（不删 / 不简化 / 不"优化"） - `codeFile` 单文件用 string 也可，但**统一**用 string[] 更一致（md 中 Instance 2/8/9/11/12/13/14/15/16 是数组，Instance 1/3/4/5/6/7/10 是单文件——executor 自行决定 string vs string[]，但所有单文件**必须** 统一成 string 或全部 string[]，**不混用**） - **推荐**：单文件 string，多文件 string[]（按 md 原始） - 数字转义 / 反斜杠：`verifyHint` 含 grep regex，注意 JSON 双引号转义 - `notes` 段含 markdown 链接、行号、中文 — 保留原样（utf-8 + 转义 \） ### Deliverable 2 — 新 JSON Schema 文件 **路径**：`src/design-system/translation/schemas/axis-implementation-map.schema.json` **完整 schema**（spec §2.1 草案）： ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "axis-implementation-map.schema.json", "title": "Axis Implementation Map", "description": "figma↔code axis 映射真源 — 每条 instance 登记 figma 组件 axis 在 code 端的实际实现层级 + 锚点。schema 字段同 axis-implementation-map.md 章节 3（plan owner SoT，本 schema 是 audit 消费契约）。", "type": "object", "required": ["version", "instances"], "additionalProperties": false, "properties": { "$schema": { "type": "string" }, "version": { "const": 1 }, "instances": { "type": "array", "items": { "type": "object", "required": [ "id", "figmaComponent", "figmaComponentSetIds", "figmaAxis", "figmaValue", "codeImplementationLayer", "codeFile", "codeAnchor" ], "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9-]+$", "description": "kebab-case 唯一标识" }, "figmaComponent": { "type": "string", "minLength": 1 }, "figmaComponentSetIds": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[0-9]+:[0-9]+$" } }, "figmaAxis": { "type": "string", "minLength": 1 }, "figmaValue": { "type": "string", "minLength": 1 }, "codeImplementationLayer": { "enum": [ "css-class", "vue-prop", "vue-computed-palette", "css-custom-property-chain", "cross-component-topology" ] }, "codeFile": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } ] }, "codeAnchor": { "type": "string", "minLength": 1 }, "verifyHint": { "type": "string" }, "notes": { "type": "string" } } } } } } ``` ### Deliverable 3 — 归档 md + 更新活跃 docs 引用 #### 3.1 归档原 md ```bash mkdir -p docs/internal/_archive/translation-md-pre-schema git mv src/design-system/translation/axis-implementation-map.md docs/internal/_archive/translation-md-pre-schema/axis-implementation-map.md ``` 在归档文件**顶部**加注释（注释加在文件第 1 行前，原 md 内容下移）： ```markdown ``` #### 3.2 更新 2 处活跃 SoT 引用 grep 出 8 处引用（plan owner pre-baseline 已 grep）。**只更新 2 处活跃 SoT**，6 处历史 prompt / 1 处历史 plan **不动**： **更新（2 处）**： | 文件 | 路径定位 | 改法 | |---|---|---| | `docs/PROJECT_GOAL.md` | 任何指向 `axis-implementation-map.md` 的路径 | 改成 `axis-implementation-map.json`（注意 `docs/` 内部相对路径） | | `docs/meta-rules.md` | 任何指向 `axis-implementation-map.md` 的路径 | 同上 | **不动（7 处）**——保历史 prompt 与 plan 的 git history fidelity： - `docs/internal/_prompts/t1b-progress-pseudo-theme-fix.prompt.md` - `docs/internal/_prompts/t1a-fix-v2-round1-plan-supplement.prompt.md` - `docs/internal/_prompts/t1a-fix-v2-round3-bug-fixes.prompt.md` - `docs/internal/_prompts/t1c-extract-recurse-children-round1-plan-only.prompt.md` - `docs/internal/_prompts/t1b-head-darktheme-alias-to-prop-aliases.prompt.md` - `docs/internal/_prompts/t1a-fix-v2-round2-implementation.prompt.md` - `docs/internal/_prompts/t1a-fix-v2-round1-plan-only.prompt.md` - `docs/internal/_plans/t1a-fix-v2-plan.md` - `docs/internal/_plans/t1c-extract-recurse-plan.md` **不动理由**：这些是历史 executor prompt 与 plan，已 executed；改它们会丢失"当时 prompt 是这样写的"实证。 --- ## 4. 执行步骤（按顺序） 1. 起手 §0 pre-flight 全绿 2. Read axis-implementation-map.md 全文（19.7KB，单文件可一次性 read） 3. 按 §3 Deliverable 1 schema 把 16 个 instance 转 JSON，逐条 fidelity 检查 4. 写 Deliverable 2 schema 文件 5. 跑 JSON schema 验证（ajv 或 node 自写）确保 JSON 通过 schema 6. 按 §3.3.1 归档 md 7. grep 2 处活跃 SoT 引用并替换 8. 跑 §5 验收命令 9. STOP + 报告 --- ## 5. 验收命令 ```bash # Deliverable 1 + 2 — JSON 文件存在 + schema 通过 test -f src/design-system/translation/axis-implementation-map.json test -f src/design-system/translation/schemas/axis-implementation-map.schema.json # JSON schema 验证（如果 repo 有 ajv-cli 安装；否则用 node + ajv import） # 推荐用 Node 一行验证： node -e " const Ajv = require('ajv'); const schema = require('./src/design-system/translation/schemas/axis-implementation-map.schema.json'); const data = require('./src/design-system/translation/axis-implementation-map.json'); const ajv = new Ajv({ strict: true }); const validate = ajv.compile(schema); if (!validate(data)) { console.error(validate.errors); process.exit(1); } console.log('OK:', data.instances.length, 'instances passed schema'); " # 预期：OK: 16 instances passed schema # fidelity 检查 — 16 instances 全在 node -e "console.log(require('./src/design-system/translation/axis-implementation-map.json').instances.length)" # 预期：16 # Deliverable 3 — md 已归档 test -f docs/internal/_archive/translation-md-pre-schema/axis-implementation-map.md test ! -f src/design-system/translation/axis-implementation-map.md # 活跃 SoT 引用已更新 grep -l "axis-implementation-map.md" docs/PROJECT_GOAL.md docs/meta-rules.md # 预期：（空 — 应 0 匹配） grep -l "axis-implementation-map.json" docs/PROJECT_GOAL.md docs/meta-rules.md # 预期：两个文件都列出 # 历史 prompt / plan 引用应保持不变 grep -c "axis-implementation-map.md" docs/internal/_prompts/t1a-fix-v2-round1-plan-only.prompt.md # 预期：>0（仍引用 md，因这是历史快照） # 全套现有 audit 0 回归（最重要） pnpm test # 105 passed | 1 skipped pnpm exec vue-tsc --noEmit # 0 错 pnpm audit:design-system # 全 pass pnpm audit:figma-conformance # 全 pass pnpm audit:docs-site # 全 pass pnpm audit:published-vs-code # 38 matched / 0 figma-only / 0 code-only pnpm audit:no-hardcoded-design-tokens # baseline 状态 pnpm audit:icon-fill-currentcolor # 0 finding pnpm audit:component-no-inline-svg # baseline 状态 pnpm audit:component-tokens # 全 pass pnpm audit:tokenized-diff # baseline 状态 ``` **任一验收 fail → STOP，不要硬上**，报告给 plan owner。 --- ## 6. 报告格式（STOP 后必交） 按这格式给 plan owner： ```markdown ## Sprint 1 完成报告 ### 改动文件清单 - [ ] 新建 src/design-system/translation/axis-implementation-map.json - [ ] 新建 src/design-system/translation/schemas/axis-implementation-map.schema.json - [ ] git mv → docs/internal/_archive/translation-md-pre-schema/axis-implementation-map.md (+ ARCHIVED 注释) - [ ] docs/PROJECT_GOAL.md 引用更新 - [ ] docs/meta-rules.md 引用更新 ### 验收结果 - JSON schema 验证：[OK / FAIL 详情] - 16 instances fidelity check: [OK / fail 哪个] - pnpm test: [105 passed | 1 skipped / fail 详情] - vue-tsc: [0 错 / 报错] - 全 audit 套：[全 pass / 哪个回归] ### 实际耗时 [Xh，对比 spec §4 估计 ~1 day] ### Sprint 1 跑出来的实情，calibrate Sprint 2 估时建议 [Sprint 2 prop-aliases.md split 估 2-3 day。Sprint 1 实跑后，prop-aliases.md 的 11 个 table 字段是否 uniform 看起来如何？跑了 sprint 1 后 plan owner 把 sprint 2 重估的 input] ### 未解决 / 待 plan owner 决策项 [列出 sprint 1 中遇到的歧义，如：某 instance 字段格式异常 / codeAnchor 行号已 stale / verifyHint 跑不通 — plan owner 决定下个 sprint 处理] ``` --- ## 7. 严格不做的事（executor 边界） executor 是单一决策源模式（AGENTS.md §工作流），sprint 1 内**不要**： - ❌ 修改 audit 脚本（grep 实证 0 引用，本 sprint 0 audit 改动） - ❌ 触碰 prop-aliases.md / divergences.md / icon-aliases.ts / token-aliases.ts（sprint 2-4 处理） - ❌ 触碰 figma-extract-rules.draft.md（spec §6 D1：留 draft，不进 v0.3.0） - ❌ 调整 16 instance 的内容 / 修复 stale 锚点（fidelity 优先；stale 锚点放报告里给 plan owner，sprint 4 audit 实现时再处理） - ❌ 自创新 instance / 删 instance（fidelity = 1:1） - ❌ 改 STATUS.md / tracker.md / CHANGELOG.md（最终 sprint 4 时做 release wrap-up） - ❌ 不要 commit — 让 plan owner 审完后用户决定 commit 节奏 - ❌ 不要写 retrospect — sprint 4 最后写 如有疑似 blocker（如某 instance 字段 md 中已破损无法 parse），**STOP** 报告，不要"修一下顺手"——破损本身是 plan owner 需要决策的 finding。 --- ## 8. 完成后 STOP 把报告交给 plan owner（Claude Code），由 plan owner 复审 + 用户决定： - 是否 commit sprint 1 - 是否进 sprint 2 - 是否 calibrate spec § 5 估时表