# 2026-06-01 — Component Affordances：AI 组合组件语义层

> 类型：新 doc 基础设施 / 新 pattern。触发复盘条件：发现新可复用 pattern（component affordance 层，对标 icon affordance 层）。

## 背景 / 触发

用户观察：AI 设计产品时没识别到 `InputNumber` 已内置 `step`（以及 `min/max/property1`），就用 input + 两个按钮自己拼了一个步进器。要求「整理其他组合组件说明，类似图标组件的说明，方便 AI 更好利用它设计产品」。

根因：图标早有语义层（`affordance-categories.json`：`when_to_use` / `synonyms` / `visual_signature`）解决「别自画 SVG」，但**组合组件没有等价层**。`components.manifest.json` 只有 `figmaName` / `variantAxes` / `variants`，没有「这组件内置了什么 / 别自拼什么 / 跟谁组合」。`figma-component-catalog.md` 有，但它是 mockup 任务导向（library key / frame used-by），不是 code 产品设计导向。

## 做了什么

新建 component affordance 语义层（对标 icon affordance 层）：

- **真源** `docs/internal/component-affordances.json` — 34 个 canonical 组件全覆盖。每条核心字段：`built_in_features`（内置能力 + 用哪个 prop/轴开）、`do_not_hand_compose`（反模式）、`composition`（contained_by / contains）、实证 `code_props`、`npm_export`、`synonyms_en/zh`、`when_to_use`。
- **视图** `component-affordances.md` — 由 `generate-component-affordances.mjs` 生成（导出 `renderMarkdown` 供 audit 复用），按 category 分组 + 速查索引。
- **防漂移** `audit-component-affordances.mjs`：① code_name↔canonical 双向覆盖（无 silent gap）② `npm_export` 与 `src/canonical/index.ts` 一致 ③ `code_props` 真实存在于 defineProps ④ MD 未 stale。已挂 pre-commit 条件 gate（staged 命中 SoT/canonical 时跑）+ AGENTS.md Sprint Self-Audit §H 登记。

## 决策 / 取舍

1. **格式选 JSON SoT + 生成 MD**（不是直接写 MD，也不是塞进 catalog）。理由：唯一能给两类受众（code + mockup）共用、且可机器校验防漂移的形态——和图标当初从散文升级到结构化 SoT 同一个理由。catalog 头部加交叉链接、声明「不重复登记 props」，避免第二真源。
2. **覆盖全 34 个**（不只「组合组件」）。理由：统一真源 + 「有什么组件」可发现性 + audit 能断言完整覆盖。深度按组件分级（富特性满字段，原子件轻字段但保留 `do_not_hand_compose`）。
3. **plan owner 直接 author**（用户授权）。本是 docs/internal 数据 + Infrastructure 小脚本，比为「读每个组件再写条目」专设 executor prompt 省一个 round-trip。

## 实证发现（不是凭印象）

- 抽 props 时核 `src/canonical/index.ts`：**ButtonBridge 的 npm 导出名是 `Button`**（不是 ButtonBridge）。
- **InputBoxBase / SelectBoxBase / PillCounter 不在 npm 公开导出**（内部 base / 未导出）→ 标 `npm_export:null` + 指向 Line/Filled 变体，audit 校验这一致性。
- audit 负向测试：注入假 prop + 改 JSON → 正确 fail（[D]+[E]），恢复后 PASS，证明不是空跑。

## 并行 session race

本 session 全程有并行 session 在 ship CANONICAL-012 + a11y + M-DISCIPLINE 并直推 master、改 STATUS.md。按 [[user_parallel-sessions]] + pickup §2 race 警告：收尾前 `git log`/`git status` 实证并行线已 wrap、STATUS 已是其版本且工作树干净，我的改动是纯增量无 overlap，才动手；STATUS 条目 prepend 在其 CANONICAL-012 之前保留全文；`phase0-ledger.md`(M, 非我改) 不 stage。

## 后续 / 可能延伸

- 文案口径（summary / when_to_use / do_not_hand_compose）首版由 plan owner 拟，后续可按真实使用反馈收敛。
- 未来可把本 JSON 喂进 AI manifest（T4b）作为 code-to-figma / 多模态合成的 composition 锚点。
- 新组件加入 canonical 时，audit 会强制补 entry（双向覆盖），不会 silent 漏。