component-states

name	component-states
description	定义 UI 组件的所有状态时使用。适用于按钮、表单、列表、对话框等组件的状态完整覆盖。优先使用 8 种核心状态（默认/悬停/聚焦/禁用/加载/成功/错误/空/权限）。

组件状态设计

适用场景

• 单个组件的状态完整定义
• 列表、表单、按钮等高频组件
• 给前端的状态实现说明
• 避免"只画静态页面"

核心原则

一个组件至少有 5 种状态，不止"默认"和"hover"
缺失任何状态都会导致用户体验断裂
状态必须前端可实现、QA 可测试

8 种核心状态

1. 默认（Default）
   组件正常显示，无交互

2. 悬停（Hover）
   鼠标悬停，提供视觉反馈

3. 聚焦（Focus）
   键盘 Tab 到该组件，无障碍必备

4. 禁用（Disabled）
   不可交互，显示原因

5. 加载（Loading）
   异步操作进行中

6. 成功（Success）
   操作完成的反馈

7. 错误（Error）
   操作失败 / 数据错误

8. 空（Empty）
   无数据 / 无结果

高频组件的额外状态

列表：
  - 部分加载（无限滚动）
  - 加载更多失败
  - 筛选结果为空（vs 完全无数据）

表单：
  - 校验中
  - 已修改未保存（dirty）
  - 已提交未确认

按钮：
  - 长按 / Active
  - 主按钮 / 次按钮 / 文本按钮（变体）

对话框：
  - 确认操作中
  - 不可关闭（处理中）

权限相关：
  - 无权限查看
  - 无权限编辑（只读）
  - 需要登录

状态设计模板

按钮组件

## Button 组件状态

| 状态 | 触发条件 | 视觉变化 | 行为 |
|------|---------|---------|------|
| Default | 默认显示 | 主色背景 | 可点击 |
| Hover | 鼠标悬停 | 主色加深 10% | 可点击 |
| Focus | 键盘 Tab | 显示焦点环（蓝色 outline） | 可点击 |
| Active | 鼠标按下 | 主色加深 20% | 触发动作 |
| Disabled | 不可用 | 灰色背景 + 50% 透明度 | 不可点击 |
| Loading | 异步操作中 | 显示 Spinner，文字隐藏 | 不可点击 |

表单字段

## Input 组件状态

| 状态 | 触发条件 | 视觉变化 | 用户行动 |
|------|---------|---------|---------|
| Empty | 默认 | 灰色边框 + placeholder | 输入 |
| Focus | 点击/Tab 进入 | 主色边框 + 显示 helper | 输入 |
| Filled | 有值 | 灰色边框 + 显示值 | 编辑 |
| Validating | 失焦后异步校验 | 边框 + Spinner | 等待 |
| Valid | 校验通过 | 绿色边框 + ✅ | 继续 |
| Invalid | 校验失败 | 红色边框 + 错误信息 | 修改 |
| Disabled | 不可编辑 | 灰色背景 | 无 |

列表组件

## List 组件状态

| 状态 | 触发条件 | 显示内容 | 用户行动 |
|------|---------|---------|---------|
| Loading | 初始加载 | Skeleton 占位 | 等待 |
| Has Data | 有数据 | 列表项 | 浏览/操作 |
| Empty | 无数据 | 空状态图 + 文案 + 主操作 | 创建第一项 |
| Filter Empty | 筛选无结果 | "无匹配结果" + 清除筛选 | 调整筛选 |
| Error | 加载失败 | 错误信息 + 重试 | 重试 |
| Loading More | 加载下一页 | 底部 Spinner | 等待 |
| End | 已加载全部 | "没有更多了" | 无 |
| No Permission | 无查看权限 | 权限提示 + 申请链接 | 申请 |

对话框

## Dialog 组件状态

| 状态 | 触发条件 | 显示内容 | 行为 |
|------|---------|---------|------|
| Closed | 默认 | 不显示 | - |
| Opening | 触发打开 | 渐入动画 | 不可交互 |
| Open | 已显示 | 完整内容 + 操作按钮 | 可交互 |
| Confirming | 用户确认中 | 主按钮 Loading | 不可关闭 |
| Closing | 触发关闭 | 渐出动画 | 不可交互 |

状态对照清单

每个组件设计时填写：

## [组件名] 状态清单

✅ Default
✅ Hover
✅ Focus
✅ Disabled
✅ Loading
✅ Success
✅ Error
✅ Empty
✅ Permission（如适用）

总计：[N] 个状态

每个状态需要：
□ 触发条件
□ 视觉变化（颜色/边框/图标/文字）
□ 用户可执行的操作
□ 自动转换条件（如 Loading → Success）

工作流程

1. 列出所有需要的组件（来自 page-structure）
2. 对每个组件应用 8 种状态清单
3. 删除不适用的状态
4. 添加组件特有的状态
5. 定义每个状态的触发条件
6. 定义状态之间的转换
7. 输出状态对照表
8. 转交 design-handoff 交接给前端

质量自检

□ 是否覆盖了 8 种核心状态
□ 是否考虑了组件特有状态
□ 每个状态是否有触发条件
□ 每个状态是否有视觉变化
□ 状态转换是否清晰
□ 是否考虑了无障碍（Focus 状态）
□ 错误状态是否可恢复

常见坑

1. 只画 Default 和 Hover——忽略 Loading/Error/Empty
2. Disabled 没有原因——用户不知道为什么不能点
3. 空状态太"空"——只有空白没有引导
4. 错误不可恢复——只显示"出错了"没有重试
5. Loading 长时间无反馈——用户以为卡死
6. 筛选无结果 = 完全空——不区分两种空
7. 没有 Focus 状态——键盘用户无法操作
8. 状态转换不清——Loading → ? 用户不知道

配套模板

• templates/interaction-state-template.md — 通用交互状态模板（按钮/表单/列表/对话框）
• templates/empty-state-pattern-template.md — 空状态设计模板

与其他 skill 的协作

上游：
  page-structure → 列出页面需要的组件

平行：
  atomic-design → 组件分层
  accessibility → Focus 状态要求
  design-tokens → 颜色/边框 token

下游：
  design-handoff → 交接所有状态给前端