/interaction-specification

name: ui-designer/interaction-specification
description: 交互规范方法论，基于 Laws of UX、Material Design Motion、HIG 等开源原则，定义加载/空状态、反馈层级、微交互、手势与无障碍交互
version: 2.0.0
agent: ui-designer
type: methodology
user-invocable: false
agent-invocable: true
dependencies:
- ui-designer/design-system
  triggers:
- 需要定义交互行为时
- 需要处理边界情况时
- 需要确保无障碍访问时
  metadata:
  internal: true
  references:
  - "Laws of UX (Jon Yablonski): https://lawsofux.com/"
  - "Material Design Motion: https://m3.material.io/styles/motion"
  - "Apple HIG - Motion: https://developer.apple.com/design/human-interface-guidelines/motion"
  - "WAI-ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/"
  - "Refactoring UI - Feedback: https://www.refactoringui.com/"

交互规范方法论

适用场景

定义用户与界面的交互细节。核心原则：**每一个用户操作都必须有明确、即时、可理解的反馈**；每一个系统状态都必须有对应的展示方式。

交互设计核心定律（Laws of UX）

在设计交互时，始终考虑以下定律：

| 定律 | 含义 | 交互应用 | | ------------------ | ------------------------ | ---------------------------------------- | | **Fitts 定律** | 目标越大、越近，点击越快 | 常用操作放在拇指可达区；按钮足够大 | | **Hick 定律** | 选项越多，决策越慢 | 减少每次呈现的选项数；分步引导 | | **Jakob 定律** | 用户期望一致性 | 遵循平台惯例和用户已有心智模型 | | **Miller 定律** | 工作记忆 7±2 项 | 分组、分页，不要一次塞太多 | | **Tesler 定律** | 复杂度守恒 | 把复杂度从用户转移到系统，不要让用户承担 | | **Parkinson 定律** | 工作会填满可用时间 | 限制功能范围，保持聚焦 | | **峰终定律** | 用户记住峰值和结尾 | 确保关键时刻体验出色 |

---

反馈层级（Feedback Hierarchy）

用户操作后，根据**影响范围**和**紧急程度**选择反馈方式。不要所有操作都弹 Toast。

| 层级 | 方式 | 适用场景 | 持续时间 | | ---------------- | ---------------- | ---------------------------- | ------------- | | **L1: 内联反馈** | 组件自身状态变化 | 按钮按下、输入聚焦、勾选成功 | 即时，无持续 | | **L2: Toast** | 轻量通知 | 操作成功、轻微警告 | 3-5s 自动消失 | | **L3: Banner** | 顶部横幅 | 需要用户注意但不阻塞 | 可手动关闭 | | **L4: Modal** | 模态确认 | 危险操作、需要决策 | 直到用户响应 | | **L5: 全屏** | 整页状态 | 加载、错误、空状态 | 直到状态改变 |

**原则**：能用 L1 就不用 L2，能用 L2 就不用 L3。高优先级操作（删除）才用 L4。

Toast 设计

┌─────────────────────────────────┐
│  [✓]  操作成功        [×]       │
└─────────────────────────────────┘

| 属性 | 值 | | -------- | ----------------------------- | | 高度 | 48px | | 内边距 | 12px 16px | | 圆角 | `radius-md` (8px) | | 阴影 | `shadow-lg` | | 最大宽度 | 420px | | 位置 | 顶部居中（距顶 24px）或右下角 |

**Toast 类型**：

| 类型 | 颜色 | 图标 | 时长 | 示例 | | ------- | ---- | ---- | --------------- | -------------------- | | Success | 绿 | ✓ | 3s | 「保存成功」 | | Info | 蓝 | ℹ | 3s | 「已复制到剪贴板」 | | Warning | 橙 | ⚠ | 4s | 「存储空间不足」 | | Error | 红 | ✕ | 5s 或不自动消失 | 「网络错误，请重试」 |

**Toast 原则**：

• 不要放需要用户操作的内容（放 Modal）
• 不要同时显示多个 Toast（队列或合并）
• Error Toast 不自动消失，让用户有时间阅读
• 有 `aria-live="polite"` 让屏幕阅读器播报

---

加载状态

加载策略决策

根据**预期等待时间**选择加载方式：

| 等待时间 | 方式 | 说明 | | ---------- | --------------------- | -------------------------- | | < 100ms | 无反馈 | 人类感知不到延迟 | | 100ms - 1s | Spinner / 骨架屏 | 快速操作，不要让用户觉得卡 | | 1s - 5s | 进度条 + 状态文字 | 告诉用户正在做什么 | | > 5s | 分阶段进度 + 预估时间 | 让用户知道还要等多久 |

> **原则**（来自 Nielsen Norman Group）：超过 1 秒必须给反馈，超过 10 秒必须给进度指示。

加载场景

| 场景 | 方式 | 视觉 | | ------------ | ------------------------------ | ------------------------------ | | 页面首次加载 | 骨架屏（Skeleton） | 灰色占位块模拟内容结构 | | 按钮提交 | 按钮内 Spinner | 按钮文字变「提交中」+ 旋转图标 | | 列表加载更多 | 底部 Spinner | 「加载中...」文字 | | 局部刷新 | 区域内 Spinner / 脉冲 | 不影响其他区域 | | 搜索 | 输入框内 Spinner（延迟 300ms） | 避免每次按键都显示 | | 文件上传 | 进度条 + 百分比 | 显示已上传 / 总大小 |

骨架屏设计

┌──────────────────────────────────┐
│  ████████                         │  ← 标题占位（比真实标题短）
│  █████████████                    │  ← 描述占位
│                                  │
│  ████  ████████████████           │  ← 列表项
│  ████  ████████████████           │
│  ████  ████████████████           │
└──────────────────────────────────┘

• 模拟真实内容的**结构和比例**，不是随机色块
• 使用 `neutral-100` 背景 + shimmer 动画（1.5s 循环）
• 不要在骨架屏上显示真实数据占位符
• 加载完成后内容直接显示，不要先消失再出现

---

空状态

空状态不是「没有内容」，而是**引导用户下一步行动**的机会。

空状态类型与设计

| 类型 | 原因 | 设计重点 | | ---------- | ------------------ | -------------------------------- | | **初始空** | 用户从未创建过内容 | 引导创建：插图 + 说明 + CTA 按钮 | | **搜索空** | 搜索无结果 | 建议：检查关键词、清除筛选 | | **错误空** | 网络/权限错误 | 解决：重试按钮、联系支持 | | **权限空** | 无权访问 | 告知：需要什么权限、如何申请 | | **删除空** | 内容已被删除 | 恢复：撤销按钮（30s 内） |

空状态结构

┌─────────────────────────────────────┐
│                                     │
│            [插图/图标]               │  ← 视觉锚点（非装饰）
│                                     │
│           主标题（一句话）           │  ← 说明发生了什么
│      副标题（为什么 / 怎么办）       │  ← 引导下一步
│                                     │
│         [主操作按钮]                 │  ← 明确的行动号召
│                                     │
└─────────────────────────────────────┘

**原则**：

• 插图与场景相关，不要用通用的「空盒子」图标
• 主标题不超过 12 字，副标题不超过 30 字
• 必须有 CTA 按钮（除非是权限/错误，提供「返回」或「重试」）
• 语气友好，不指责用户（不说「你没有数据」，说「开始创建你的第一个项目吧」）

---

错误处理

错误信息三要素

每个错误必须回答：**出了什么问题？为什么？怎么解决？**

┌─────────────────────────────────────────┐
│ ⚠ 保存失败                                │  ← 问题
│ 网络连接中断，请检查网络后重试             │  ← 原因 + 解决
│                              [重试]       │  ← 行动
└─────────────────────────────────────────┘

错误信息写作原则

• **说人话**：不要显示「Error 500」或堆栈跟踪
• **给方案**：不只说「失败」，要说「请重试」或「联系管理员」
• **可恢复**：提供撤销、重试、返回等操作
• **不指责**：不说「你输入错误」