# Prop Aliases ## Known Entries > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: component-prop`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 ## Vue 生态增强（代码侧添加，Figma 无对应） > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: vue-ecosystem-addition` / `scope: runtime-addition`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 ## 组件级命名映射 > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: component-naming`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 ## 枚举值命名映射 > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: value-alias`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 ## 项目级 GLOBAL axis alias（影响所有组件） > GLOBAL alias 表达"figma axis 在概念层是 X，在 canonical/derived 层应该统一为 Y"。 > 当前 canonical 可能仍保留 figma 原 prop 名（如 Tooltip 的 `darkTheme`），generator 应按本表派生 derived 字段（如 `variant.theme`）供下游 (filter / α audit) 使用——不破坏 canonical 现有 API。 ### 表 A — Axis 名 alias（figma → canonical/derived） > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: global-axis-alias`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 ### 表 B — Axis 值 alias（figma value → derived value） > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: axis-value-alias`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 ### 表 C — 当前已识别影响范围 > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: identified-impact-scope`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 ### 历史 - T1a 修补阶段：在 audit 脚本 `GLOBAL_AXIS_ALIASES` 常量里硬编码 - T1b 头号任务（2026-04-29）：迁到本文件作为真源，audit 脚本读本文件 - T2 sample Tooltip 扩展（commit 8870419）：generator 实现"axis 命名保 figma 原 prop 名 + 派生 theme 字段"模式 - Phase A0 cleanup（2026-05-06）：自由文本改表格 schema 让 generator auto-discovery 能 parse --- ## Figma axis 处理规则（影响所有 axis 派生） > 本段独立于上面的 alias 真源——alias 是"figma X → canonical Y"映射。 > 本段是**generator / audit 在应用 axis 入派生流程前的通用预处理规则**。 ### 规则 1: 单值 axis 跳过 如果 figma `COMPONENT_SET` 内某 axis 在**所有 variants 中只有 1 个 unique value**（如 PromptMessage 全 8 variants 共享 `interact=Yes`），该 axis **不进** generator 输出的 `axes` 数组，**不派生** propByAxis 映射（不 bind canonical prop）。 理由： - 单值 axis 在 figma 设计上本就不构成可选择维度（用户没法在这个 axis 上做选择） - canonical 通常没有对应 prop——单值 axis 的语义往往是 figma 用其它 component property（如 boolean `Show close icon`）独立控制，与 variant axis 解耦 - 强行 bind 单值 axis 到 prop 会导致 propByAxis 派生失败 + canonical actual props mismatch 实施位置：[`figma-sync/generate-docs-figma-members.mjs`](../../../figma-sync/generate-docs-figma-members.mjs) discover 阶段——收集每 axis 全部 unique values；`size === 1` → 跳过该 axis（warn 提示）。 实证案例：PromptMessage `interact=Yes` 全 8 variants 单值——figma 用独立 boolean property `Show close icon` 控制关闭图标 → canonical `closable: boolean` prop 通过本文件"Known Entries"段 `closable ↔ showCloseIcon` alias 登记。`interact` 不应再当 variant axis bind canonical prop。 --- ## Boolean Property Aliases（figma boolean component property ↔ canonical boolean prop） > Phase X.1 + X.2（2026-05-07）实证补充：figma `get_design_context` 返回的 component property 类型定义 (`type XxxProps = { ... }`) 暴露 boolean component properties。本表登记 figma boolean → canonical prop 映射。 > 实证 source：`figma-data/normalized/figma-mcp-cache/.tsx`（MCP cache backfill） > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: boolean-property`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 --- ## Slot Property Aliases（figma instance-swap / children property ↔ canonical Vue slot） > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: slot-property`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 --- ## Sub-component Composition Aliases（figma data-name ↔ canonical component import + variant） > 实证 source：figma cache 中 `data-name="..."` JSX 属性。Audit 脚本提取后通过本表交叉验证 canonical 实际 import 是否对齐。 > Vue 模块系统已自动 propagate（canonical 改 Select → 引用 Select 的 Pagination 自动 rebuild）；本表用于 audit-time alignment verification。 ### 表 A — 标准 design-system 复用 (canonical import 期望) > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: composition-component`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 ### 表 B — Icon refs (figma `icon//` → canonical ``) > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: composition-icon`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。 详细 figma name → canonical name → svg key 三层映射见 [`icon-aliases.ts`](icon-aliases.ts)（unchanged，本表只做 composition alignment 索引）。 ### 表 C — Button refs (BRIDGE-Tier3 阻塞，当前使用 native ``) > entries 已迁到 [`prop-aliases.json`](./prop-aliases.json) `scope: composition-button-blocked`。 > 详细字段定义见 [`schemas/prop-aliases.schema.json`](./schemas/prop-aliases.schema.json)。