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)
- 触发(Trigger):什么启动了交互?(用户操作 / 系统状态)
- 规则(Rules):交互如何进行?
- 反馈(Feedback):用户看到/听到什么?
- 循环(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 使用原则
- 优先用语义元素:
<button>优于<div role="button"> - ARIA 只在语义不足时使用:不要给原生元素加多余 ARIA
aria-label用于无文字的图标按钮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
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.
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.
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.
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.
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.
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.