Is interaction-spec safe to install?

SaferSkills independently audited interaction-spec (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.

CategoryWeightCategory scoreContribution

Securityprompt, exec, net, exfil, eval

35%

100

35.0 pts

Supply chainhash, typosquat, maintainer, lockfile

20%

100

20.0 pts

Maintenancestaleness, pinning, CI

15%

100

15.0 pts

TransparencySKILL.md, perms, README

15%

100

15.0 pts

Communityinstalls, verify, response

15%

100

15.0 pts

Findings & checks · 0 flagged

Securityscore 100 · 0 findings

✓—All security checks passedNo findings in this category for the latest scan.pass

Supply chainscore 100 · 0 findings

✓—All supply chain checks passedNo findings in this category for the latest scan.pass

Maintenancescore 100 · 0 findings

✓—All maintenance checks passedNo findings in this category for the latest scan.pass

Transparencyscore 100 · 0 findings

✓—All transparency checks passedNo findings in this category for the latest scan.pass

Communityscore 100 · 0 findings

✓—All community checks passedNo findings in this category for the latest scan.pass

The primary manifest — the file an agent reads to learn what this artifact does.

pm-03-design/skills/interaction-spec/SKILL.md · 1 file

pm-03-design/skills/interaction-spec/SKILL.md13.3 KB · Markdown

name: interaction-spec

description: 当需要将用户流程和原型设计转化为完整的交互设计规范时使用。交互设计规范文档自动生成，包含交互状态机、动画规范、手势操作、反馈机制、无障碍交互和异常状态处理。关键词：交互设计规范、交互规范、状态机、动画规范、手势操作、交互反馈、无障碍交互、交互文档、动效规范。

metadata:

module: "产品构思与设计"

sub-module: "产品设计与原型"

type: "pipeline"

version: "3.0"

domain_tags: ["互联网", "软件", "通用"]

trigger_examples:

- "交互规范怎么写"

- "帮我写交互设计文档"

- "动效和手势怎么定义"

interaction_mode: "ai_suggest_human_approve"

交互设计规范文档生成

核心原则

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

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

交互模式

🤖→👤 AI建议人类审批

输入

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

降级策略

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

执行步骤

Step 1：交互状态机定义

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

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

Step 2：动画与过渡意图

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

过渡意图（不定义具体缓动函数和时长）：

通用过渡：应感觉自然流畅
进入动画：应有减速感，元素从远处靠近
退出动画：应有加速感，元素向远处离开
频繁切换：应干脆利落，不拖泥带水

动画意图标准（不定义具体毫秒数）：

微交互（按钮反馈、开关切换）：应即时可感知
小型过渡（下拉展开、轻量反馈）：应快速完成
大型过渡（页面切换、模态框）：应有节奏感
复杂动画（数据可视化、3D变换）：应有叙事感

动画性能：仅使用 transform 和 opacity，避免 layout 和 paint 触发
减弱动画：prefers-reduced-motion 适配规则

Step 3：手势与操作意图

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

点击/按压：

触摸目标应满足平台无障碍标准（iOS/Android/Web 各有规范）
长按操作需有触觉或视觉反馈
双击操作需有合理的时间窗口

滑动/拖拽：

滑动操作应有合理的触发灵敏度（避免误触）
滑动应有惯性和衰减效果
边缘滑动需保留系统手势

缩放/旋转：

缩放范围应有合理上下限
旋转操作应有吸附辅助

键盘操作：

Tab 顺序与焦点管理规则
快捷键映射表
Enter/Space 激活规则

Step 4：反馈机制规范

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

即时反馈：

用户操作后需立即感知系统已接收
按钮按下态、链接悬停态
输入框聚焦态、开关切换态

过程反馈：

长时间操作需提供进度感知
加载状态需有视觉占位，避免页面跳动
上传/下载等可量化操作需提供进度指示

结果反馈（操作完成后）：

成功：操作结果需明确反馈给用户，成功状态需可区分
警告：需引起用户注意但不阻断操作，用户需能主动确认或等待自动消退
错误：错误状态需明确区分于正常状态，用户需能快速识别并理解错误原因
信息：需提供补充说明但不干扰主流程

无反馈场景：明确列出不需要反馈的操作及理由

Step 5：异常状态交互

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

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

Step 6：无障碍交互规范

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

WCAG 2.1 AA 合规：

可感知：文本替代、时基媒体替代、适应性、可辨别
可操作：键盘可操作、充足时间、癫痫安全、可导航
可理解：可读性、可预测性、输入辅助
健壮性：兼容辅助技术

焦点管理：焦点陷阱（Modal）、焦点还原（关闭Modal后）、焦点顺序
ARIA标注：角色（role）、状态（aria-state）、属性（aria-property）使用规范
屏幕阅读器：关键交互的朗读文本和朗读顺序

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定义一致

interaction-spec— agent skill

Is interaction-spec safe to install?

交互设计规范文档生成

核心原则

交互模式

输入

降级策略

执行步骤

Step 1：交互状态机定义

Step 2：动画与过渡意图

Step 3：手势与操作意图

Step 4：反馈机制规范

Step 5：异常状态交互

Step 6：无障碍交互规范

Step 7：报告组装

输出

输出文件

Markdown 报告结构

JSON 结构

质量检查

输出校验规则

决策规则

降级策略

上游变更响应

上游变更影响

下游通知机制

与prd.json数据契约对齐

Audit the pieces. Scan the whole. Decide.