# INFRA-F59 外观变体 prop 命名统一 Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 把 8 个组件的外观变体 prop 统一命名（`fill`/`type`/`color`/`state`），消灭 Button `style` footgun，加一道 SoT 驱动的横向一致性 audit gate 防漂回。 **Architecture:** 只改 **canonical 公开层 + config + 派生物**，base 组件内部 prop 名不动（canonical→base 边界映射沿用现有 normalize 模式）。改名靠现有 pre-commit gate（binding-config-parity / component-affordances / demo-parity / vitest）保原子性；新 gate 在所有改名完成后最后接线（届时真实 config 已干净）。Figma 属性名保留、code 用规范名、差异登记 `prop-aliases.json` approved-alias。破坏性改名（无 runtime alias），走 MIGRATION + changeset。 **Tech Stack:** Vue 3.5 SFC (`defineCustomElement`) · Node 22+ 原生 TS stripping (audit 直接 `import` `.ts` config) · vitest · Gitea/GitHub CI + husky pre-commit + prepublishOnly。 ## Global Constraints - **Figma 属性名保留不变**：`data-figma-*` 属性 key 照旧（`data-figma-style`/`-tag`/`-property1`/`-property2`），value 改从新 prop 取。`prop-aliases.json` 记 code 新名 ↔ Figma 旧名 approved-alias。 - **枚举值不改**：所有值形态（`filling`/`Filled`/`Line`/大小写混用）原样保留，只改 prop 名。 - **base 组件内部 prop 名不改**：`BaseTab type` / `BaseInputNumber property1` / `BaseStepItem step-style` / Button base `canonical-style` 全不动；canonical 公开 prop 改名后在 `` 边界映射。 - **无 runtime deprecation alias**：旧 prop 名直接消失（破坏性）；靠 MIGRATION + changeset(minor/breaking) 传播。 - **规范名映射**：`fill`(填充处理) · `type`(种类) · `color`(颜色) · `state`(状态) · `size`(尺寸，仅守 casing)。 - **gate 零硬编码**：`audit-prop-naming.mjs` 读 `prop-naming-conventions.json` SoT + `import` config，不在脚本写死组件规则。 - **git**：owner 直 commit master、精确 `git add `（禁 `-A`）、commit body 按 PR 模板字段、changeset 随实质改动同 commit。视觉/`.vue` 改动 commit 需 `VISUAL_COMMIT_APPROVED=1`（见 pre-commit hook line 74-89）。 --- ### 全量改名映射（唯一真源表，所有 task 引用） | 组件 | canonical 公开旧名 | 新名 | 值（不变）| base 边界目标 prop（不改）| Figma 属性名（alias 记）| |---|---|---|---|---|---| | Button | `style` | `fill` | filling/ghost/rimless | `:canonical-style` | `style` | | Badge | `tag` | `fill` | Filled/Line | (Badge 无 base，自渲染) | `tag` | | Tab | `type` | `fill` | Line/Text/Filled(+lc) | `:type`(normalized lc) | `type` | | Tab | `property2` | `color` | White/Green(+lc) | `:active-color`(normalized) | `Property 2` | | TabList | `type` | `fill` | Line/Text/Filled(+lc) | `:type`(normalized lc) | `type` | | TabItem | `type` | `fill` | Line/Text/Filled(+lc) | `:type`(normalized lc) | `type` | | TabItem | `property1` | `state` | Normal/Active(+lc) | `:state`(normalized) | `Property 1` | | TabItem | `property2` | `color` | White/Green(+lc) | `:active-color`(normalized) | `Property 2` | | Steps | `stepStyle` | `type` | number/icon | `:step-style` | `Property 1`(见 Task 4 step 1 核实) | | StepItem | `stepStyle` | `type` | number/icon | `:step-style` | `Property 1`(同上) | | StepItem | `style`(删除) | — | — | — | — | | InputNumber | `property1` | `type` | Default/Only Add/Only Reduce/Readonly | `:property1` | `Property 1`(已有 alias entry 006) | | Pagination | `type`(不改) | `type` | Classic/Simple/Small | — | 打 `axis:'kind'` | | Badge | `type`(不改) | `type` | Circle/Rectangle | — | 打 `axis:'kind'` | > **axis 标记**（Task 7 加进 config，供 gate 概念一致性校）：`fill` 组 → `axis:'fill'`；`type` 组（含不改的 Pagination/Badge `type`）→ `axis:'kind'`；`color` 组 → `axis:'color'`；TabItem `state` → `axis:'state'`。 --- ### Task 1: Button `style` → `fill`（含 React remap 移除） **Files:** - Modify: `src/canonical/ButtonBridge.vue`（defineProps + default + data-figma + 转发） - Modify: `src/web-components/components.config.ts:121-125`（Button `style` prop entry） - Modify: `src/web-components/reserved-names.ts`（删 `style: 'variant'`） - Modify: `docs/internal/component-affordances.json:1024`（Button `style` → `fill`） - Modify: `scripts/generate-render-verification-manifest.mjs`（Button 块 codeProps `style` → `fill`） - Modify: `playground/docs/pages/ButtonPage.vue`（props 对象 `style:` → `fill:` + 展示串） - Modify: `react-pilot/src/wrappers/Button.test.tsx:28`（`variant="ghost"` → `fill="ghost"`） - Modify: `tests/Button.test.ts`（**只改** canonical 公开 `style:` → `fill:`；`canonicalStyle:` 是 base prop **不动**） - Regenerate: react bindings（`Button.tsx` / `types.ts` 派生）+ affordances `.md` + manifest **Interfaces:** - Produces: Button canonical 公开 prop `fill?: 'filling' | 'ghost' | 'rimless'`（default `'filling'`）；React 侧直接暴露 `fill`（不再 remap 为 `variant`）。 - [ ] **Step 1: 改 ButtonBridge.vue** `src/canonical/ButtonBridge.vue` 改 4 处：type 别名重命名、defineProps、default、data-figma + 转发。 第 11 行 `type Style = ...` → 保留类型体、重命名： ```ts type Fill = 'filling' | 'ghost' | 'rimless' ``` 第 22 行 `style?: Style` → `fill?: Fill` 第 32 行 `style: 'filling',` → `fill: 'filling',` 第 48 行 `'data-figma-style': props.style,` → 保持 key、改取值：`'data-figma-style': props.fill,` 第 62 行 `:canonical-style="style"` → `:canonical-style="fill"`（base prop 名 `canonical-style` 不变，只改绑定源） - [ ] **Step 2: 改 components.config.ts Button entry** `src/web-components/components.config.ts` 第 106 行注释 `// defineProps: color, ..., style, theme` → `..., fill, theme`。 第 121-125 的 prop entry 整块替换（**不写 `axis` 字段**——`axis` 在 Task 7 才加进 `PropConfig` 接口，Task 1-6 提前写会 TS 报「对象字面量多余属性」）： ```ts { name: 'fill', tsType: `'filling' | 'ghost' | 'rimless'`, jsdoc: 'Appearance/fill variant enum (filling/ghost/rimless).', }, ``` - [ ] **Step 3: 移除 reserved-names remap** `src/web-components/reserved-names.ts` 第 6-8 行 `RESERVED_NAME_REMAP` 清空为空对象（保留文件 + 函数，见 spec §7 item 2）： ```ts export const RESERVED_NAME_REMAP: Record = {} ``` 第 2-5 行注释更新：把「A canonical design axis literally named one of these...」保留，追加一句：`// Currently empty — Button's former `style` axis was renamed to `fill` (INFRA-F59), so no remap is needed. Kept as the extension point for any future reserved-name collision.` - [ ] **Step 4: 更新 affordances SoT + manifest 生成器 + 派生物** `docs/internal/component-affordances.json` 第 1024 行 `{ "name": "style", "type": "filling | ghost | rimless", "default": "filling" }` → `{ "name": "fill", ... }`。 `scripts/generate-render-verification-manifest.mjs` Button 块（`grep -n "figmaName: 'Button'"` 附近，非 url-link 那个）里所有 `style:` codeProps key → `fill:`。用 scoped 替换后 `grep -n "style:" ` 确认 Button 块内无残留（注意别动 url-link 块）。 `playground/docs/pages/ButtonPage.vue`： - 第 74 行展示串 `'style=rimeless'`（注意原 typo）→ `'fill=rimless'` - 第 121-138 等 props 对象里的 `style: ''` → `fill: ''`（`figmaVariantName` 字符串内的 `style=` 是 Figma 变体名**保留不动**，只改 JS `props: { ... style: ... }` 对象的 key）。命令：审 `grep -n "style:" playground/docs/pages/ButtonPage.vue`，逐条把对象 key 改 `fill:`。 `react-pilot/src/wrappers/Button.test.tsx` 第 28 行 `variant="ghost"` → `fill="ghost"`。 `tests/Button.test.ts`：第 85、290 行（及任何）canonical 公开 `style: ''` → `fill: ''`。**`canonicalStyle:`（base prop，line 16/50/71/104…）保持不变**——它是 `src/components/Button/Button.vue` 的内部 contract prop，本 plan 不动 base。 - [ ] **Step 5: 重生成派生物** ```bash pnpm run gen:react-bindings # = node scripts/generate-react-bindings.mjs（重生成 react-pilot Button.tsx/types.ts：fill，不再 variant） node scripts/generate-component-affordances.mjs # 重生成 affordances .md 视图 node scripts/generate-render-verification-manifest.mjs # 重生成 manifest（Button codeProps fill） ``` - [ ] **Step 6: 跑测试验证** Run: `pnpm exec vue-tsc --noEmit && pnpm test` Expected: PASS（Button/Canonical/ButtonPage 相关全绿；`