AGENT SKILL

interaction-specification

暂无简介

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

03 SKILL.md 正文

交互规范方法论

适用场景

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

交互设计核心定律(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」或堆栈跟踪
  • 给方案:不只说「失败」,要说「请重试」或「联系管理员」
  • 可恢复:提供撤销、重试、返回等操作
  • 不指责:不说「你输入错误」,说「请输入有效的邮箱地址」

参考:Apple HIG 要求错误信息用友好语气,避免技术术语。


微交互(Micro-interactions)

微交互是小而有意义的反馈,让界面感觉有生命。

微交互四要素(Dan Saffer)

  1. 触发(Trigger):什么启动了交互?(用户操作 / 系统状态)
  2. 规则(Rules):交互如何进行?
  3. 反馈(Feedback):用户看到/听到什么?
  4. 循环(Loops & Modes):交互如何结束?是否进入新模式?

常见微交互

触发 反馈 时长 缓动
按钮 hover 背景色加深 + cursor:pointer 150ms ease-out
按钮按下 scale(0.98) + 背景加深 100ms ease-out
卡片 hover 阴影加深 + translateY(-2px) 200ms ease-out
勾选 checkbox ✓ 图标弹出动画 200ms spring
开关切换 圆点滑动 + 背景色变化 200ms ease-in-out
收藏按钮 心形放大 + 粒子效果 300ms spring
下拉刷新 箭头旋转 + 刷新图标 300ms ease-in-out

微交互原则

  • 即时:操作后 100ms 内必须有反馈
  • 克制:不是每个元素都需要动效
  • 可逆:动画可以反向播放(关闭 = 打开的反向)
  • 尊重偏好:prefers-reduced-motion 时禁用非必要动画

动效规范

页面过渡

场景 动效 参数
页面进入 淡入 + 上移 300ms ease-out, opacity 0→1, translateY(8px)→0
页面退出 淡出 200ms ease-in, opacity 1→0
列表项进入 错峰淡入 每项延迟 50ms, 200ms ease-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%)
展开/收起 高度动画 250ms ease-in-out

参考:Material Design 3 的「Shared axis」「Fade」「Container transform」三种过渡模式可根据场景选用。


手势设计(移动端)

触控目标

  • 最小:44×44px(HIG)/ 48×48dp(Material Design)
  • 推荐:48×48px,相邻元素间距 ≥ 8px
  • 拇指热区:屏幕底部 1/3 区域最易操作

手势映射

手势 用途 注意
点击 选择、激活 必须有视觉反馈(ripple 或 scale)
长按 上下文菜单、多选 必须有触觉反馈(haptic)
滑动 列表项操作(删除/归档) 必须可撤销、有视觉提示
下拉 刷新 必须有 loading 指示
捏合 缩放图片/地图 必须支持双击重置
拖拽 排序、移动 必须有拖拽中视觉反馈

原则:手势是快捷方式,不是唯一途径。每个手势操作都必须有对应的按钮操作(无障碍)。


键盘导航

焦点顺序

  • Tab 顺序遵循视觉阅读顺序(左到右、上到下)
  • 不要用 tabindex > 0 破坏自然顺序(用 DOM 顺序控制)
  • 模态框打开时锁定焦点在框内

快捷键

按键 功能
Tab / Shift+Tab 前后导航
Enter 激活按钮、链接、提交
Space 切换 checkbox/radio/switch
Esc 关闭弹窗、下拉、取消
↑ ↓ ← → 列表、菜单、标签页导航
Home / End 列表首尾
Cmd/Ctrl + Enter 表单提交(可选便利键)

焦点样式

:focus-visible {
  outline: 2px solid var(--primary-500);
  outline-offset: 2px;
  border-radius: 4px;
}
  • 用 :focus-visible 而非 :focus(鼠标点击不显示,键盘显示)
  • 不要用 outline: none 而不提供替代
  • 焦点环颜色与背景对比度 ≥ 3:1

屏幕阅读器

ARIA 使用原则

  1. 优先用语义元素:<button> 优于 <div role="button">
  2. ARIA 只在语义不足时使用:不要给原生元素加多余 ARIA
  3. aria-label 用于无文字的图标按钮
  4. aria-live 用于动态内容更新

关键 ARIA 模式

组件 ARIA
图标按钮 aria-label="删除"
加载中 aria-busy="true"
错误提示 aria-live="polite" + aria-describedby
模态框 role="dialog" aria-modal="true" aria-labelledby
Tab 切换 role="tablist" role="tab" aria-selected
折叠面板 aria-expanded aria-controls

响应式交互

断点 交互调整
< 640px 手机 全屏弹窗、底部抽屉、大触控目标、手势操作
640-1024px 平板 侧边抽屉、适中触控目标、悬停+点击
> 1024px 桌面 居中弹窗、悬停效果、键盘快捷键、小触控目标

移动端特有:

  • 弹窗从底部滑入(Bottom Sheet),不是居中
  • 操作按钮放在屏幕底部(拇指可达)
  • 表单输入时键盘弹出,确保输入框可见(scroll into view)
  • 不要依赖 hover(移动端没有 hover)

自检清单

  • [ ] 每个用户操作都有明确反馈(内联 / Toast / Modal)
  • [ ] 加载策略按等待时间分级(<1s / 1-5s / >5s)
  • [ ] 空状态有插图 + 说明 + CTA 按钮
  • [ ] 错误信息包含:问题 + 原因 + 解决方案
  • [ ] 微交互动效 ≤ 300ms,尊重 prefers-reduced-motion
  • [ ] 所有可交互元素键盘可达,焦点可见
  • [ ] 图标按钮有 aria-label,动态内容有 aria-live
  • [ ] 移动端触控目标 ≥ 44×44px,手势有替代按钮操作
  • [ ] 参考了 Laws of UX 中至少 3 条定律

常见误区

❌ 所有操作都弹 Toast — 大多数反馈应该是内联的(按钮状态变化) ❌ 加载只用 Spinner — 长加载必须有进度和预估时间 ❌ 空状态只写「暂无数据」 — 必须引导用户下一步 ❌ 错误信息显示堆栈跟踪 — 用户看不懂,也不安全 ❌ 动效超过 500ms — 用户会觉得慢,微交互应 < 300ms ❌ 手势是唯一操作方式 — 必须有对应的按钮操作 ❌ 移除 focus outline — 键盘用户无法知道焦点在哪

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k