/component-specification

name: ui-designer/component-specification
description: UI 组件规范方法论，基于 Material Design 3、Ant Design、Carbon Design System 等开源组件库，定义组件解剖、变体决策、状态完备性与无障碍要求
version: 2.0.0
agent: ui-designer
type: guideline
user-invocable: false
agent-invocable: true
dependencies:
- ui-designer/design-system
  triggers:
- 需要设计组件时
- 需要定义组件规范时
- 前端开发需要组件文档时
  metadata:
  internal: true
  references:
  - "Material Design 3 Components: https://m3.material.io/components"
  - "Ant Design Components: https://ant.design/components/overview"
  - "Carbon Design System Components: https://carbondesignsystem.com/components/"
  - "WAI-ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/"
  - "Refactoring UI - Components: https://www.refactoringui.com/"

UI 组件规范方法论

适用场景

基于设计系统，定义可复用的 UI 组件规范。本方法论不只是罗列组件参数，而是教你**如何做组件决策**：何时用哪种变体、状态如何设计、无障碍如何保证。

组件设计框架

每个组件的规范必须回答以下 5 个问题： 1. **解剖（Anatomy）**：组件由哪些部分组成？ 2. **变体（Variants）**：有哪些视觉变体？何时用哪种？ 3. **状态（States）**：所有交互状态是否完备？ 4. **无障碍（A11y）**：键盘、屏幕阅读器、ARIA 角色是否正确？ 5. **边界（Edge cases）**：长文本、空内容、加载中如何处理？

> **参考**：Material Design 3 每个组件文档都包含 Anatomy、Behavior、Theming 三部分；Carbon Design System 提供 Anatomy、Placement、Style 结构。

组件状态完备性检查

每个交互组件必须覆盖以下状态（不适用的需显式标注「不适用」）：

| 状态 | 说明 | 必须覆盖 | | ---------- | --------- | ----------------------- | | `default` | 默认态 | ✅ 所有组件 | | `hover` | 鼠标悬停 | ✅ 桌面端可交互组件 | | `focus` | 键盘聚焦 | ✅ 所有可交互组件 | | `active` | 按下/激活 | ✅ 按钮、链接 | | `disabled` | 禁用 | ✅ 表单组件、按钮 | | `loading` | 加载中 | ✅ 提交类按钮、异步组件 | | `error` | 错误状态 | ✅ 表单组件 | | `selected` | 选中态 | ✅ 选择类组件 |

---

1. 按钮 (Button)

解剖

┌──────────────────────────────────┐
│  [图标]  按钮文字  [图标/加载]    │
└──────────────────────────────────┘
  前缀      标签        后缀

变体决策

| 变体 | 何时使用 | 何时不用 | | ------------------ | --------------------------------------------------------- | -------------------------------- | | **Primary** | 每个区域的主要操作（提交、确认、保存）。一个区域最多 1 个 | 不要用于次要操作，避免视觉噪声 | | **Secondary** | 次要操作（取消、返回），与 Primary 配对 | 不要用于需要强调的操作 | | **Ghost/Tertiary** | 低优先级操作、工具栏操作、列表内操作 | 不要用于需要明确点击的场景 | | **Danger** | 不可逆的危险操作（删除、清空） | 不要用于普通操作，即使是红色主题 | | **Link** | 内联导航、文本中的操作 | 不要用于表单提交 |

> **原则**（来自 Refactoring UI）：一个区域内，Primary 按钮最多 1 个。如果有 2 个「主要」操作，说明你没有区分主次。

尺寸

| 尺寸 | 高度 | 内边距 | 字号 | 触控目标 | | ---- | ---- | ------ | ---- | ----------------------- | | `sm` | 32px | 0 12px | 14px | ≥ 32px | | `md` | 40px | 0 16px | 14px | ≥ 40px（移动端 ≥ 44px） | | `lg` | 48px | 0 20px | 16px | ≥ 48px |

无障碍

• 使用原生 `<button>` 元素，不要用 `<div onclick>`
• 禁用状态用 `disabled` 属性，不要只靠样式
• 加载状态用 `aria-busy="true"`，文字用 `aria-label` 标注「提交中」
• 图标按钮必须有 `aria-label`（不要只放图标）
• Danger 按钮除了红色，还要有文字明确说明后果

边界处理

• 文字过长：截断 + `title` tooltip，或换行（不推荐按钮换行）
• 图标+文字：图标与文字间距 8px
• 纯图标按钮：必须有 tooltip 说明功能

---

2. 输入框 (Input)

解剖

┌──────────────────────────────────────────────┐
│ 标签 *                                        │  ← Label（必填标红星）
│ ┌──────────────────────────────────────────┐ │
│ │ [前缀图标]  输入内容            [后缀操作] │ │  ← 输入框
│ └──────────────────────────────────────────┘ │
│ 辅助说明文字                                   │  ← Helper text
│ 错误提示文字                                   │  ← Error message
└──────────────────────────────────────────────┘

标签与占位符

• **标签必须可见** — 不要只用 placeholder 当标签（placeholder 消失后用户不知道该填什么）
• **必填字段**：标签后加红色 `*`，不要只靠 placeholder 写「（必填）」
• **placeholder**：只放格式提示（如 `YYYY-MM-DD`），不放标签

> **参考**：Nielsen Norman Group 研究表明，仅用 placeholder 作为标签会显著降低表单完成率。

状态

| 状态 | 边框 | 背景 | 附加 | | ---- | ------------- | ------------ | --------------------------- | | 默认 | `neutral-300` | 白 | - | | 悬停 | `neutral-400` | 白 | - | | 聚焦 | `primary-500` | 白 | 2px `primary-500` 外发光 | | 错误 | `error-500` | 白 | 下方显示错误文字 + 错误图标 | | 禁用 | `neutral-200` | `neutral-50` | cursor: not-allowed | | 只读 | `neutral-200` | `neutral-50` | 可选复制按钮 |

无障碍

• `<label for="input-id">` 关联标签和输入框
• 错误信息用 `aria-describedby` 关联到输入框
• 聚焦时输入框边框变色 + 外发光（不要只靠颜色，加外发光确保可见）
• 密码框有「显示/隐藏」切换按钮，按钮有 `aria-label`
• 数字输入不要用 `type="number"`（有兼容性问题），用 `inputmode="numeric"` + 验证

---

3. 选择器 (Select / Dropdown)

变体决策

| 类型 | 选项数 | 搜索 | 适用场景 | | ------------------- | ------ | ---- | ---------------------- | | **原生 Select** | < 7 | 否 | 简单选择，移动端体验好 | | **自定义 Dropdown** | 7-50 | 可选 | 需要自定义样式、分组 | | **搜索选择器** | > 50 | 是 | 大量选项（国家、用户） | | **级联选择** | 层级 | 是 | 省市区、分类 |

无障碍

• 触发元素用 `role="combobox"` + `aria-expanded`
• 下拉列表用 `role="listbox"`，选项用 `role="option"` + `aria-selected`
• 键盘支持：↑↓ 导航、Enter 选择、Esc 关闭、输入首字母跳转
• 关闭后焦点回到触发元素

---

4. 复选框 / 单选框 (Checkbox / Radio)

决策

| 场景 | 用 Checkbox | 用 Radio | | ------------- | ----------- | --------- | | 多选 | ✅ | ❌ | | 单选 | ❌ | ✅ | | 开关（开/关） | ❌ | 用 Switch | | 同意条款 | ✅（单个） | ❌ |

解剖

Checkbox:
┌──┐
│✓│  选项文字
└──┘

Radio:
○  选项文字

无障碍

• 用原生 `<input type="checkbox">` / `<input type="radio">`
• 每个选项有 `<label>` 包裹或关联
• 单选组用 `<fieldset>` + `<legend>` 包裹
• Checkbox 半选状态用 `indeterminate` 属性

---

5. 开关 (Switch)

何时用 Switch vs Checkbox

• **Switch**：即时生效的设置（如「深色模式」「通知开关」），切换立即生效
• **Checkbox**：需要提交才生效的选择（如「记住我」「同意条款」）

无障碍

• 用 `role="switch"` + `aria-checked`
• 或用原生 checkbox + switch 样式
• 开关状态变化时，如有延迟加载，显示 loading 态

---

6. 卡片 (Card)

解剖

┌─────────────────────────────────┐
│  [媒体区：图片/图标/渐变]        │  ← Media（可选）
├──────────────────