Applicable Scenarios
- Complete state definition for a single component
- High-frequency components such as lists, forms, and buttons
- State implementation notes for frontend
- Avoid "drawing only static pages"
Core Principles
一个组件至少有 5 种状态，不止"默认"和"hover"
缺失任何状态都会导致用户体验断裂
状态必须前端可实现、QA 可测试
8 Core States
1. 默认（Default）
组件正常显示，无交互
2. 悬停（Hover）
鼠标悬停，提供视觉反馈
3. 聚焦（Focus）
键盘 Tab 到该组件，无障碍必备
4. 禁用（Disabled）
不可交互，显示原因
5. 加载（Loading）
异步操作进行中
6. 成功（Success）
操作完成的反馈
7. 错误（Error）
操作失败 / 数据错误
8. 空（Empty）
无数据 / 无结果
Additional States for High-Frequency Components
列表：
- 部分加载（无限滚动）
- 加载更多失败
- 筛选结果为空（vs 完全无数据）
表单：
- 校验中
- 已修改未保存（dirty）
- 已提交未确认
按钮：
- 长按 / Active
- 主按钮 / 次按钮 / 文本按钮（变体）
对话框：
- 确认操作中
- 不可关闭（处理中）
权限相关：
- 无权限查看
- 无权限编辑（只读）
- 需要登录
State Design Template
Button Component
## Button 组件状态
| 状态 | 触发条件 | 视觉变化 | 行为 |
|------|---------|---------|------|
| Default | 默认显示 | 主色背景 | 可点击 |
| Hover | 鼠标悬停 | 主色加深 10% | 可点击 |
| Focus | 键盘 Tab | 显示焦点环（蓝色 outline） | 可点击 |
| Active | 鼠标按下 | 主色加深 20% | 触发动作 |
| Disabled | 不可用 | 灰色背景 + 50% 透明度 | 不可点击 |
| Loading | 异步操作中 | 显示 Spinner，文字隐藏 | 不可点击 |
Form Fields
## Input 组件状态
| 状态 | 触发条件 | 视觉变化 | 用户行动 |
|------|---------|---------|---------|
| Empty | 默认 | 灰色边框 + placeholder | 输入 |
| Focus | 点击/Tab 进入 | 主色边框 + 显示 helper | 输入 |
| Filled | 有值 | 灰色边框 + 显示值 | 编辑 |
| Validating | 失焦后异步校验 | 边框 + Spinner | 等待 |
| Valid | 校验通过 | 绿色边框 + ✅ | 继续 |
| Invalid | 校验失败 | 红色边框 + 错误信息 | 修改 |
| Disabled | 不可编辑 | 灰色背景 | 无 |
List Component
## List 组件状态
| 状态 | 触发条件 | 显示内容 | 用户行动 |
|------|---------|---------|---------|
| Loading | 初始加载 | Skeleton 占位 | 等待 |
| Has Data | 有数据 | 列表项 | 浏览/操作 |
| Empty | 无数据 | 空状态图 + 文案 + 主操作 | 创建第一项 |
| Filter Empty | 筛选无结果 | "无匹配结果" + 清除筛选 | 调整筛选 |
| Error | 加载失败 | 错误信息 + 重试 | 重试 |
| Loading More | 加载下一页 | 底部 Spinner | 等待 |
| End | 已加载全部 | "没有更多了" | 无 |
| No Permission | 无查看权限 | 权限提示 + 申请链接 | 申请 |
Dialog
## Dialog 组件状态
| 状态 | 触发条件 | 显示内容 | 行为 |
|------|---------|---------|------|
| Closed | 默认 | 不显示 | - |
| Opening | 触发打开 | 渐入动画 | 不可交互 |
| Open | 已显示 | 完整内容 + 操作按钮 | 可交互 |
| Confirming | 用户确认中 | 主按钮 Loading | 不可关闭 |
| Closing | 触发关闭 | 渐出动画 | 不可交互 |
State Checklist
Fill in when designing each component:
## [组件名] 状态清单
✅ Default
✅ Hover
✅ Focus
✅ Disabled
✅ Loading
✅ Success
✅ Error
✅ Empty
✅ Permission（如适用）
总计：[N] 个状态
每个状态需要：
□ 触发条件
□ 视觉变化（颜色/边框/图标/文字）
□ 用户可执行的操作
□ 自动转换条件（如 Loading → Success）
Workflow
1. 列出所有需要的组件（来自 page-structure）
2. 对每个组件应用 8 种状态清单
3. 删除不适用的状态
4. 添加组件特有的状态
5. 定义每个状态的触发条件
6. 定义状态之间的转换
7. 输出状态对照表
8. 转交 design-handoff 交接给前端
Quality Self-Check
□ 是否覆盖了 8 种核心状态
□ 是否考虑了组件特有状态
□ 每个状态是否有触发条件
□ 每个状态是否有视觉变化
□ 状态转换是否清晰
□ 是否考虑了无障碍（Focus 状态）
□ 错误状态是否可恢复
Common Pitfalls
- Only drawing Default and Hover— Ignoring Loading/Error/Empty
- Disabled has no reason— Users do not know why they cannot click
- Empty state is too "empty"— Only blank space with no guidance
- Errors are unrecoverable— Only showing "An error occurred" with no retry
- Loading has no feedback for a long time— Users think it is frozen
- No filter results = completely empty— Not distinguishing the two kinds of empty
- No Focus state— Keyboard users cannot operate
- State transitions are unclear— Loading → ? Users do not know
Companion Templates
templates/interaction-state-template.md— General interaction state template (buttons/forms/lists/dialogs)templates/empty-state-pattern-template.md— Empty state design template
Collaboration with Other Skills
上游：
page-structure → 列出页面需要的组件
平行：
atomic-design → 组件分层
accessibility → Focus 状态要求
design-tokens → 颜色/边框 token
下游：
design-handoff → 交接所有状态给前端