ui-designer-interaction-specification

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. 及时反馈：用户操作后立即给予反馈
2. 清晰引导：明确告诉用户下一步该做什么
3. 容错性：允许用户撤销、修改操作
4. 一致性：相同操作在不同场景下行为一致
5. 可访问性：支持键盘、屏幕阅读器等辅助技术

交互规范

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 无障碍设计
[颜色对比度、键盘导航、屏幕阅读器、触控目标]

关键原则

1. 及时反馈：用户操作后立即给予反馈
2. 清晰引导：明确告诉用户下一步该做什么
3. 容错性：允许用户撤销、修改操作
4. 可访问性：支持键盘、屏幕阅读器等辅助技术

常见误区

❌ 无加载提示：操作后没有任何反馈，用户不知道是否成功 ❌ 空状态不友好：只显示"无数据"，没有引导用户下一步 ❌ 过度动画：所有元素都加动画，影响性能和体验 ❌ 忽略无障碍：不支持键盘导航，颜色对比度不足