Interaction spec

交互设计规范文档生成

核心原则

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

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

交互模式

🤖→👤 AI建议人类审批

输入

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

降级策略

缺失的上游输入	降级方案	输出影响
用户流程缺失	基于原型推导交互流程	流程待确认，交互状态机可能不够完整
原型规格缺失	基于用户流程生成交互规范框架	待原型验证，组件交互规格可能不够精确
设计交接文档缺失	交互规范独立编号	后续需与交接文档对齐，令牌引用可能不一致
品牌规范缺失	采用中性交互风格	待品牌确认，动画风格可能需要调整

执行步骤

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：报告组装

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

输出

输出文件

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

Markdown 报告结构

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

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

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

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

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

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

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

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

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

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": []
  }
}

质量检查

检查项	标准	不通过处理
状态机完整	8种基础状态全覆盖	补充缺失状态定义
动画性能合规	仅使用transform/opacity	替换不合规动画属性
无障碍合规	WCAG 2.1 AA全部覆盖	补充缺失无障碍规范
反馈全覆盖	每种用户操作有对应反馈	补充缺失反馈或标注"无反馈"理由

输出校验规则

字段路径	类型	必填	说明
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定义一致