---
name: interaction-spec
description: 当需要将用户流程和原型设计转化为完整的交互设计规范时使用。交互设计规范文档自动生成，包含交互状态机、动画规范、手势操作、反馈机制、无障碍交互和异常状态处理。关键词：交互设计规范、交互规范、状态机、动画规范、手势操作、交互反馈、无障碍交互、交互文档、动效规范。
metadata:
  module: "产品构思与设计"
  sub-module: "产品设计与原型"
  type: "pipeline"
  version: "3.0"
  domain_tags: ["互联网", "软件", "通用"]
  trigger_examples:
    - "交互规范怎么写"
    - "帮我写交互设计文档"
    - "动效和手势怎么定义"
  interaction_mode: "ai_suggest_human_approve"
execution_depth:
  default: standard
  quick_description: "直接输出交互规格和状态设计"
  deep_description: "完整规格 + 状态机全覆盖 + 动效规范 + 无障碍交互设计"
---

# 交互设计规范文档生成

## 核心原则

**交互规范是用户体验的宪法**

交互设计规范确保产品中每个交互行为都有一致、可预测、无障碍的体验。规范不是限制创造力，而是保证基础体验质量的底线，让设计师可以专注于创新而非重复定义基础交互。

## 交互模式

🤖→👤 AI建议人类审批

## 输入

| 输入项 | 类型 | 必填 | 来源 | 说明 |
|--------|------|------|------|------|
| 用户流程 | JSON | 是 | design-userflow | 用户流程图、状态转换、决策节点 |
| 原型规格 | JSON | 是 | design-prototype | 原型设计、交互标注、组件规格 |
| 设计交接文档 | markdown | 否 | design-handoff-spec | 设计令牌、组件规格、响应式断点 |
| 品牌规范 | text | 否 | 用户输入 | 品牌调性、动画风格偏好 |

### 降级策略

| 缺失的上游输入 | 降级方案 | 输出影响 | 数据获取说明 |
|---------------|---------|---------|------------|
| 用户流程缺失 | 基于原型推导交互流程 | 流程待确认，交互状态机可能不够完整 | 要求用户提供用户操作流程描述或上传design-userflow输出文件 |
| 原型规格缺失 | 基于用户流程生成交互规范框架 | 待原型验证，组件交互规格可能不够精确 | 要求用户提供原型设计描述或上传design-prototype输出文件 |
| 设计交接文档缺失 | 交互规范独立编号 | 后续需与交接文档对齐，令牌引用可能不一致 | 要求用户提供设计令牌和组件规格或上传design-handoff-spec输出文件 |
| 品牌规范缺失 | 采用中性交互风格 | 待品牌确认，动画风格可能需要调整 | 要求用户提供品牌调性和动画风格偏好 |

## 执行步骤

### Step 1：交互状态机定义 [核心]

为每个核心组件和页面定义交互状态机：

1. **状态枚举**：Default / Hover / Active / Focus / Disabled / Loading / Error / Empty / Success
2. **状态转换表**：触发条件、转换动作、过渡意图
3. **状态优先级**：多状态叠加时的优先级规则（如 Disabled + Error）
4. **状态持久性**：瞬时状态 vs 持续状态的保持规则

### Step 2：动画与过渡意图 [核心]

定义产品中动画和过渡效果的**意图**，具体实现参数由 UI Skill（ext-interaction-design + page-builder）基于 visual_direction 决定：

1. **过渡意图**（不定义具体缓动函数和时长）：
   - 通用过渡：应感觉自然流畅
   - 进入动画：应有减速感，元素从远处靠近
   - 退出动画：应有加速感，元素向远处离开
   - 频繁切换：应干脆利落，不拖泥带水
2. **动画意图标准**（不定义具体毫秒数）：
   - 微交互（按钮反馈、开关切换）：应即时可感知
   - 小型过渡（下拉展开、轻量反馈）：应快速完成
   - 大型过渡（页面切换、模态框）：应有节奏感
   - 复杂动画（数据可视化、3D变换）：应有叙事感
3. **动画性能**：仅使用 transform 和 opacity，避免 layout 和 paint 触发
4. **减弱动画**：`prefers-reduced-motion` 适配规则

### Step 3：手势与操作意图 [核心]

定义各平台的手势操作**意图和约束**，具体阈值由 UI Skill 基于平台规范和 visual_direction 决定：

1. **点击/按压**：
   - 触摸目标应满足平台无障碍标准（iOS/Android/Web 各有规范）
   - 长按操作需有触觉或视觉反馈
   - 双击操作需有合理的时间窗口
2. **滑动/拖拽**：
   - 滑动操作应有合理的触发灵敏度（避免误触）
   - 滑动应有惯性和衰减效果
   - 边缘滑动需保留系统手势
3. **缩放/旋转**：
   - 缩放范围应有合理上下限
   - 旋转操作应有吸附辅助
4. **键盘操作**：
   - Tab 顺序与焦点管理规则
   - 快捷键映射表
   - Enter/Space 激活规则

### Step 4：反馈机制规范 [核心]

定义用户操作的反馈标准：

1. **即时反馈**：
   - 用户操作后需立即感知系统已接收
   - 按钮按下态、链接悬停态
   - 输入框聚焦态、开关切换态
2. **过程反馈**：
   - 长时间操作需提供进度感知
   - 加载状态需有视觉占位，避免页面跳动
   - 上传/下载等可量化操作需提供进度指示
3. **结果反馈**（操作完成后）：
   - 成功：操作结果需明确反馈给用户，成功状态需可区分
   - 警告：需引起用户注意但不阻断操作，用户需能主动确认或等待自动消退
   - 错误：错误状态需明确区分于正常状态，用户需能快速识别并理解错误原因
   - 信息：需提供补充说明但不干扰主流程
4. **无反馈场景**：明确列出不需要反馈的操作及理由

### Step 5：异常状态交互 [核心]

定义异常场景的交互处理：

1. **网络异常**：需明确告知用户当前网络不可用，提供重试机会和本地可用内容
2. **数据为空**：需避免空白页面，提供引导用户产生内容的途径
3. **权限不足**：需解释权限限制原因，提供申请或替代操作途径
4. **数据超限**：需合理展示截断内容，提供查看完整内容的方式
5. **并发冲突**：需检测并告知冲突，提供用户决策的途径

### Step 6：无障碍交互规范 [核心]

确保交互符合无障碍标准：

1. **WCAG 2.1 AA 合规**：
   - 可感知：文本替代、时基媒体替代、适应性、可辨别
   - 可操作：键盘可操作、充足时间、癫痫安全、可导航
   - 可理解：可读性、可预测性、输入辅助
   - 健壮性：兼容辅助技术
2. **焦点管理**：焦点陷阱（Modal）、焦点还原（关闭Modal后）、焦点顺序
3. **ARIA标注**：角色（role）、状态（aria-state）、属性（aria-property）使用规范
4. **屏幕阅读器**：关键交互的朗读文本和朗读顺序

### Step 7：报告组装 [核心]

将以上内容组装为完整交互设计规范文档。

### 输出深度分级

| 深度级别 | 输出范围 | 说明 |
|----------|----------|------|
| quick | 交互规格和状态设计 | 核心结论 + 最小可行产物 |
| standard | 完整产物（当前默认） | 完整产物，包含全部Step输出 |
| deep | 完整规格 + 状态机全覆盖 + 动效规范 + 无障碍交互设计 | 完整产物 + 扩展分析 + 深度推演 |

## 输出

### 输出文件

| 文件 | 路径 | 说明 |
|------|------|------|
| 交互设计规范 | `output/pm-design/interaction-spec/interaction-spec.md` | 人类可读的完整规范 |
| 结构化数据 | `output/pm-design/interaction-spec/interaction-spec.json` | 机器可消费的结构化数据 |

### Markdown 报告结构

```markdown
# 交互设计规范：{产品名称}

**输出校验规则**：详见下方输出校验规则章节

## 1. 交互状态机
- 状态枚举与定义
- 状态转换表
- 状态优先级规则
- 状态持久性规则

## 2. 动画与过渡意图
- 过渡意图（自然流畅/减速感/加速感/干脆利落）
- 动画时长意图（即时可感知/快速完成/有节奏感/有叙事感）
- 性能约束
- 减弱动画适配

## 3. 手势与操作意图
- 点击/按压意图
- 滑动/拖拽意图
- 缩放/旋转意图
- 键盘操作规范

## 4. 反馈机制规范
- 即时反馈
- 过程反馈
- 结果反馈（成功/警告/错误/信息）
- 无反馈场景

## 5. 异常状态交互
- 网络异常
- 数据为空
- 权限不足
- 数据超限
- 并发冲突

## 6. 无障碍交互规范
- WCAG 2.1 AA合规检查
- 焦点管理规则
- ARIA标注规范
- 屏幕阅读器适配

## 7. 交互规范索引
- 组件×状态交叉引用表
- 动画×场景交叉引用表
```

### JSON 结构

```json
{
  "product_name": "",
  "report_date": "",
  "state_machines": {
    "states": [],
    "transitions": [
      {
        "from": "",
        "to": "",
        "trigger": "",
        "transition_intent": "",
        "completeness_check": ""
      }
    ],
    "priority_rules": [],
    "persistence_rules": []
  },
  "animation": {
    "transition_intents": [],
    "duration_intents": [],
    "performance_constraints": [],
    "reduced_motion": {}
  },
  "gestures": {
    "tap_press_intents": {},
    "swipe_drag_intents": {},
    "pinch_rotate_intents": {},
    "keyboard": {}
  },
  "feedback": {
    "immediate": [
      {
        "trigger": "",
        "intent": "",
        "completeness_check": ""
      }
    ],
    "progress": [
      {
        "trigger": "",
        "intent": "",
        "completeness_check": ""
      }
    ],
    "result": [
      {
        "trigger": "",
        "intent": "",
        "completeness_check": ""
      }
    ],
    "no_feedback_scenarios": []
  },
  "error_states": {
    "network_error": {
      "intent": "",
      "completeness_check": ""
    },
    "empty_state": {
      "intent": "",
      "completeness_check": ""
    },
    "permission_denied": {
      "intent": "",
      "completeness_check": ""
    },
    "data_overflow": {
      "intent": "",
      "completeness_check": ""
    },
    "concurrent_conflict": {
      "intent": "",
      "completeness_check": ""
    }
  },
  "accessibility": {
    "wcag_compliance": [],
    "focus_management": [],
    "aria_specifications": [],
    "screen_reader": []
  }
}
```

## 质量检查

### P0 检查（quick/standard/deep 都必须通过）

- [ ] 状态机完整（8种基础状态全覆盖）
- [ ] 动画性能合规（仅使用transform/opacity）

### P1 检查（standard/deep 必须通过）

- [ ] 无障碍合规（WCAG 2.1 AA全部覆盖）
- [ ] 反馈全覆盖（每种用户操作有对应反馈）

### P2 检查（仅 deep 必须通过）

- [ ] 扩展分析完整（深度推演和路线图已生成）
- [ ] 决策记录完整（关键决策有依据和替代方案）

## 输出校验规则

| 字段路径 | 类型 | 必填 | 说明 |
|----------|------|------|------|
| product_name | string | 是 | 产品名称 |
| report_date | string | 是 | 报告日期（ISO8601） |
| state_machines | object | 是 | 交互状态机 |
| state_machines.states | array | 是 | 状态枚举，至少8种 |
| state_machines.transitions | array | 是 | 状态转换表，每项包含 from/to/trigger/transition_intent/completeness_check |
| state_machines.priority_rules | array | 是 | 状态优先级规则 |
| animation | object | 是 | 动画与过渡意图 |
| animation.transition_intents | array | 是 | 过渡意图列表 |
| animation.duration_intents | array | 是 | 动画时长意图列表 |
| gestures | object | 是 | 手势与操作意图 |
| feedback | object | 是 | 反馈机制规范 |
| feedback.immediate | array | 是 | 即时反馈列表，每项包含 trigger/intent/completeness_check |
| feedback.result | array | 是 | 结果反馈列表，每项包含 trigger/intent/completeness_check |
| error_states | object | 是 | 异常状态交互 |
| accessibility | object | 是 | 无障碍交互规范 |
| accessibility.wcag_compliance | array | 是 | WCAG合规检查项 |

## 决策规则

- 当用户流程和原型规格均完整时，生成完整交互规范（状态机+动画+手势+反馈+无障碍）
- 当仅有用户流程时，生成交互规范框架，动画和手势规范标注"待原型验证"
- 当存在平台差异（iOS/Android/Web）时，分别定义平台特定交互规范
- 需要人类确认的决策点：动画风格偏好、无障碍合规等级（AA/AAA）、手势冲突处理策略

## 降级策略

- 当用户流程缺失时：基于原型推导交互流程，状态机可能不够完整
- 当原型规格缺失时：基于用户流程生成交互规范框架，组件交互规格待原型验证
- 当设计交接文档缺失时：交互规范独立编号，后续需与交接文档对齐
- 数据不可用时：生成通用交互规范模板，所有具体数值标注"待产品确认"

## 上游变更响应

### 上游变更影响

| 上游变更 | 影响范围 | 响应策略 |
|----------|----------|----------|
| 用户流程变更（路径/分支修改） | 交互状态机、反馈机制 | 标注受影响的状态转换，建议人类确认是否更新交互规范 |
| 原型规格变更（组件/交互修改） | 手势操作、反馈机制、异常状态 | 标注受影响的交互定义，建议人类确认是否更新 |
| 设计交接文档变更（令牌/组件调整） | 动画规范中的令牌引用 | 标注受影响的令牌引用，建议人类确认是否更新 |
| 品牌规范变更 | 动画风格、缓动函数 | 标注受影响的动画定义，建议人类确认是否调整风格 |

### 下游通知机制

| 交互规范变更类型 | 通知范围 | 通知方式 |
|-----------------|----------|----------|
| 状态机变更 | design-handoff-spec | 标记状态机变更，触发交接文档更新 |
| 动画规范变更 | design-handoff-spec | 标记动画变更，触发交接文档交互规则更新 |
| 手势规范变更 | design-handoff-spec | 标记手势变更，触发交接文档更新 |
| 无障碍规范变更 | design-handoff-spec | 标记无障碍变更，触发交接文档更新 |

## 与prd.json数据契约对齐

| 本Skill输出字段 | prd.json对应字段 | 对齐规则 |
|----------------|-----------------|---------|
| state_machines[].name | prd.json.pages[].name | 状态机名称与PRD页面名称对应 |
| state_machines[].states[] | prd.json.pages[].states[] | 状态机状态必须覆盖PRD定义的5种特殊状态（空/加载/错误/部分/权限） |
| state_machines[].states[].triggers | prd.json.pages[].states[].triggers | 状态触发条件与PRD定义一致 |
