name: ui-designer/interaction-specification
description: 交互规范，定义加载状态、空状态、反馈机制、动效、无障碍等交互细节
version: 1.0.0
agent: ui-designer
type: guideline
user-invocable: false
agent-invocable: true
dependencies:
- ui-designer/design-system
triggers:
- 需要定义交互行为时
- 需要处理边界情况时
- 需要确保无障碍访问时
交互规范
适用场景
定义用户与界面交互的细节，包括加载状态、空状态、反馈机制、动效、无障碍等，确保交互流畅、友好、可访问。
交互设计原则
- 及时反馈：用户操作后立即给予反馈
- 清晰引导：明确告诉用户下一步该做什么
- 容错性：允许用户撤销、修改操作
- 一致性：相同操作在不同场景下行为一致
- 可访问性：支持键盘、屏幕阅读器等辅助技术
交互规范
1. 加载状态
加载场景
| 场景 |
处理方式 |
时机 |
视觉表现 |
| 页面首次加载 |
骨架屏 |
首次进入页面 |
灰色占位块，模拟内容结构 |
| 页面刷新 |
顶部进度条 |
刷新页面 |
蓝色进度条，从左到右 |
| 按钮提交 |
按钮内 spinner |
点击提交按钮后 |
按钮内显示旋转图标，文字隐藏 |
| 列表加载更多 |
底部 spinner |
滚动到底部 |
底部显示"加载中..." |
| 局部刷新 |
区域内 spinner |
刷新某个区域 |
区域内显示旋转图标 |
| 搜索 |
输入框内 spinner |
输入后延迟搜索 |
输入框右侧显示旋转图标 |
骨架屏设计
┌─────────────────────────────────────┐
│ ████████ │ ← 标题占位
│ ████████████ │ ← 描述占位
│ │
│ ████ ████████████████ │ ← 列表项占位
│ ████ ████████████████ │
│ ████ ████████████████ │
└─────────────────────────────────────┘
骨架屏原则：
- 模拟真实内容的结构和布局
- 使用灰色占位块（Gray-200）
- 添加微妙的动画（shimmer效果）
- 不要显示真实数据的占位符
Spinner设计
| 尺寸 |
大小 |
线宽 |
用途 |
| sm |
16px |
2px |
按钮内、输入框内 |
| md |
24px |
2.5px |
卡片内、区域内 |
| lg |
32px |
3px |
页面级加载 |
颜色：
- 主色（Primary）：主要操作的加载
- 灰色（Gray-400）：次要操作的加载
- 白色（White）：深色背景上的加载
2. 空状态
空状态场景
| 场景 |
展示内容 |
操作引导 |
| 无数据 |
插图 + "暂无数据" |
"创建第一个项目" 按钮 |
| 搜索无结果 |
插图 + "未找到相关内容" |
"尝试其他关键词" 提示 |
| 网络错误 |
插图 + "网络连接失败" |
"重试" 按钮 |
| 权限不足 |
插图 + "无权访问" |
"返回首页" 按钮 |
| 404页面 |
插图 + "页面不存在" |
"返回首页" 按钮 |
空状态设计
┌─────────────────────────────────────┐
│ │
│ [插图/图标] │
│ │
│ 暂无数据 │
│ 您还没有创建任何项目 │
│ │
│ [创建项目] 按钮 │
│ │
└─────────────────────────────────────┘
空状态原则：
- 使用友好的插图或图标
- 说明为什么是空的
- 提供明确的操作引导
- 不要让用户感到困惑或沮丧
3. 反馈机制
Toast通知
| 类型 |
颜色 |
图标 |
持续时间 |
位置 |
| Success |
Success |
✓ |
3秒 |
顶部居中 |
| Warning |
Warning |
⚠ |
4秒 |
顶部居中 |
| Error |
Error |
✕ |
5秒 |
顶部居中 |
| Info |
Info |
ℹ |
3秒 |
顶部居中 |
Toast设计：
┌─────────────────────────────────────┐
│ [图标] 操作成功 │
└─────────────────────────────────────┘
- 背景：对应语义色
- 文字：白色
- 圆角：radius-md
- 阴影：shadow-lg
- 最大宽度：400px
- 可手动关闭（右侧×按钮）
Modal确认框
| 类型 |
用途 |
按钮 |
| 确认 |
危险操作（删除、清空） |
"取消" + "确认" |
| 警告 |
重要提示 |
"我知道了" |
| 信息 |
详细说明 |
"关闭" |
Modal设计：
┌─────────────────────────────────────┐
│ 标题 [×] │
├─────────────────────────────────────┤
│ │
│ 内容区域 │
│ │
├─────────────────────────────────────┤
│ [取消] [确认] │
└─────────────────────────────────────┘
- 背景：White
- 圆角：radius-xl
- 阴影：shadow-2xl
- 最大宽度：480px
- 遮罩：rgba(0,0,0,0.5)
表单验证
| 时机 |
验证方式 |
反馈位置 |
| 输入时 |
实时验证（延迟300ms） |
输入框下方 |
| 失焦时 |
立即验证 |
输入框下方 |
| 提交时 |
全部验证 |
输入框下方 + Toast |
错误提示：
- 颜色：Error
- 字号：14px
- 图标：✕
- 位置：输入框下方，space-2间距
4. 动效规范
页面过渡
| 场景 |
动效 |
参数 |
| 页面进入 |
淡入 |
300ms ease-out, opacity 0→1 |
| 页面退出 |
淡出 |
200ms ease-in, opacity 1→0 |
| 路由切换 |
淡入淡出 |
250ms ease-in-out |
弹窗动效
| 场景 |
动效 |
参数 |
| Modal出现 |
淡入 + 缩放 |
250ms ease-out, scale 0.95→1, opacity 0→1 |
| Modal消失 |
淡出 + 缩放 |
200ms ease-in, scale 1→0.95, opacity 1→0 |
| Drawer出现 |
滑入 |
300ms ease-out, translateX -100%→0 |
| Drawer消失 |
滑出 |
250ms ease-in, translateX 0→-100% |
微交互
| 场景 |
动效 |
参数 |
| 按钮悬停 |
背景色渐变 |
150ms ease-out |
| 按钮按下 |
缩放 |
100ms ease-out, scale 0.98 |
| 卡片悬停 |
阴影加深 |
200ms ease-out |
| 展开收起 |
高度动画 |
250ms ease-in-out |
| 淡入淡出 |
透明度 |
200ms ease-in-out |
动效原则：
- 动效要有意义，不要为了炫技
- 保持克制，不要过度动画
- 微交互要快（150ms），大动画可以慢（300ms）
- 提供关闭动画的选项（尊重用户偏好）
5. 无障碍设计
颜色对比度
| 组合 |
对比度 |
是否合规（WCAG AA） |
| Gray-900 / White |
16.1:1 |
✅ |
| Gray-700 / White |
9.5:1 |
✅ |
| Gray-500 / White |
4.6:1 |
✅ |
| Primary / White |
需计算 |
需≥4.5:1 |
对比度要求：
- 正文文字：≥4.5:1（WCAG AA）
- 大文字（18px+）：≥3:1（WCAG AA）
- 图标、UI组件：≥3:1
键盘导航
| 按键 |
功能 |
| Tab |
移动到下一个可聚焦元素 |
| Shift + Tab |
移动到上一个可聚焦元素 |
| Enter |
激活按钮、链接、提交表单 |
| Space |
切换复选框、单选框、开关 |
| Escape |
关闭弹窗、下拉菜单、取消操作 |
| 方向键 |
在列表、菜单、选项卡中导航 |
| Home / End |
跳到列表开头/结尾 |
聚焦指示：
- 所有可交互元素必须有明显的聚焦状态
- 聚焦样式：2px Primary 外发光
- 不要移除默认的 outline
屏幕阅读器
| 元素 |
ARIA 属性 |
说明 |
| 按钮 |
aria-label |
图标按钮必须有文字说明 |
| 输入框 |
aria-label 或关联 <label> |
说明输入框用途 |
| 加载状态 |
aria-busy="true" |
告知正在加载 |
| 错误提示 |
aria-live="polite" |
实时播报错误 |
| 弹窗 |
role="dialog", aria-modal="true" |
标识为对话框 |
| 导航 |
role="navigation", aria-label |
标识导航区域 |
触控目标
| 设备 |
最小尺寸 |
推荐尺寸 |
| 移动端 |
44x44px |
48x48px |
| 桌面端 |
32x32px |
40x40px |
触控原则：
- 按钮、链接等可点击元素要足够大
- 相邻元素之间要有足够间距（至少8px）
- 移动端优先考虑拇指可达区域
6. 响应式交互
断点调整
| 断点 |
交互调整 |
| < 640px (mobile) |
全屏弹窗、底部抽屉、大触控目标 |
| 640-1024px (tablet) |
侧边抽屉、适中触控目标 |
| > 1024px (desktop) |
居中弹窗、悬停效果、小触控目标 |
移动端特殊交互
| 交互 |
说明 |
| 下拉刷新 |
列表顶部下拉触发刷新 |
| 滑动删除 |
列表项左滑显示删除按钮 |
| 长按 |
长按触发上下文菜单 |
| 双击 |
双击放大图片 |
| 捏合缩放 |
图片、地图支持捏合缩放 |
输出要求
在UI设计文档中，应包含以下交互规范章节：
## 7. 交互规范
### 7.1 加载状态
[加载场景表格]
### 7.2 空状态
[空状态场景表格]
### 7.3 反馈机制
[Toast、Modal、表单验证规范]
### 7.4 动效规范
[页面过渡、弹窗动效、微交互表格]
### 7.5 无障碍设计
[颜色对比度、键盘导航、屏幕阅读器、触控目标]
关键原则
- 及时反馈：用户操作后立即给予反馈
- 清晰引导：明确告诉用户下一步该做什么
- 容错性：允许用户撤销、修改操作
- 可访问性：支持键盘、屏幕阅读器等辅助技术
常见误区
❌ 无加载提示：操作后没有任何反馈，用户不知道是否成功
❌ 空状态不友好：只显示"无数据"，没有引导用户下一步
❌ 过度动画：所有元素都加动画，影响性能和体验
❌ 忽略无障碍：不支持键盘导航，颜色对比度不足
By