# [ComponentName] · 组件元数据

> 维护规则：组件验收通过后填写，每次更新同步修改。
> 分工：identity / intent / avoid / prop.intent 由设计师主导；props 类型 / platform-diff / tokens-used 由研发填写。

---

## identity · 身份

| 字段 | 值 |
|------|-----|
| name | ComponentName |
| category | action \| input \| display \| feedback \| navigation \| layout |
| layer | atomic \| composite \| pattern |
| platforms | iOS · Android · RN |
| status | stable \| beta \| deprecated |
| version | 1.0 |

---

## intent · 使用意图

**用于：**
> 一句话说清楚这个组件解决什么问题、在什么场景下出现。
> 例：触发用户的主要或次要操作，需要用户明确点击确认。

**不用于（avoid）：**
> 列出容易被误用的场景，越具体越好。
> 例：
> - 纯展示标签（用 Tag）
> - 导航跳转（用 Link 或 TabBar）
> - 状态切换（用 SegmentedControl 或 Switch）

**相关组件（related）：**
> 列出容易混淆或可以替代的组件，说明区别。
> 例：IconButton（纯图标无文字时用）· FAB（全局唯一主操作用）

**使用限制：**
> 例：primary variant 每屏最多出现 1 个

---

## props · 接口说明

> 每个 prop 必须填 intent 字段，说明"这个 prop 控制什么"，不能只写类型。

| prop 名 | 类型 | 默认值 | intent（这个 prop 控制什么） |
|---------|------|--------|---------------------------|
| variant | `'primary' \| 'ghost' \| 'text'` | `primary` | primary=主操作·ghost=次要操作·text=最低强调，三者视觉权重依次递减 |
| size | `'large' \| 'middle' \| 'small'` | `large` | large=主要操作区·middle=常规·small=行内或紧凑场景 |
| disabled | `boolean` | `false` | 操作不可用时使用，需同时在界面上说明原因 |
| loading | `boolean` | `false` | 异步操作进行中，自动禁用点击防重复提交 |
| onPress | `() => void` | — | 点击回调，disabled/loading 为 true 时不触发 |

**slots / children：**
> 说明可以传入什么内容，以及限制。
> 例：可包含文字和 Icon，Icon 只能在文字左侧或右侧，不可单独使用（单独用 IconButton）

**events：**
> 除 onPress 外的事件，如有则列出。

---

## spacing · 间距

> 填写实际数值，不填变量名。

| 位置 | 值 |
|------|-----|
| padding-horizontal | 24（large）· 20（middle）· 16（small） |
| padding-vertical | 14（large）· 10（middle）· 8（small） |
| icon-to-text gap | 6 |

---

## tokens-used · 使用的 Token

> 列出组件直接使用的 Token，便于 AI 理解组件和 Token 系统的关联。

| 用途 | Token |
|------|-------|
| 背景色（primary） | `accent/blue_fill` |
| 文字色（primary） | `content/inverse_normal` |
| 背景色（ghost） | `fill/primary` |
| 圆角 | `radius/button_large`（large）· `radius/button_middle`（middle） |
| 按压遮罩 | `other/button_onPress`（仅交互状态，非静态） |

---

## nesting-rules · 嵌套规则

**可以包含：**
- Icon 组件（左侧或右侧）
- 纯文字

**不可以：**
- 嵌套另一个 Button
- 嵌套 Input 或表单元素

**被嵌套时：**
- 出现在 Modal 底部时，宽度撑满容器
- 出现在 Card 内时，继承 Card 的 padding，Button 本身不额外加边距

---

## platform-diff · 三端差异

| 差异点 | iOS | Android | RN |
|--------|-----|---------|-----|
| 按压反馈 | 透明度变化 | 涟漪效果（Material） | 透明度变化 |
| 字重 | SF Pro，系统默认 | Roboto，系统默认 | 跟随系统 |
| 无障碍 | accessibilityRole="button" 自动 | 自动 | 需手动设置 |

> 以上差异属正常平台特性，不算视觉走查问题。

---

## changelog · 变更记录

| 版本 | 变更内容 | 日期 |
|------|---------|------|
| 1.0 | 初始发布，含 primary / ghost / text 三种 variant | 2025-xx-xx |

---

> **填写说明**
> - intent / avoid / prop.intent：设计师填，这是 AI 理解组件的核心
> - props 类型 / platform-diff / tokens-used：研发填
> - spacing：设计师和研发对照设计稿共同确认
> - changelog：每次组件更新必填，没有记录的更新视为未发生