interaction-physics

交互物理反馈

为每个用户操作提供物理反馈：时长保持一致，缓动有意义，反馈即时到达。**首要原则：每个动画都必须有作用——确认操作、引导注意力，或说明状态变化。没有这些作用的动效应直接删除，而不是调整。**同时交付两项成果：一份项目级动画规范（确保未来的动效保持一致），以及适用范围内交互的实现代码。

何时使用 / 何时不使用

适用于：悬停／按下／聚焦反馈、进入／退出过渡（模态框、Toast、页面、列表项）、表单反馈动画、动画审查、选择时长和缓动、支持 prefers-reduced-motion。

以下情况应转交其他技能：

• 选择何时显示哪种加载指示器 → skills/frontend-design/loading-states（本技能负责为其添加动画；该技能负责选择指示器）
• 乐观 UI、感知延迟、Core Web Vitals → skills/frontend-design/performance-optimization
• 渲染管线、布局抖动、帧预算 → skills/frontend-design/design-engineer-mindset
• 非动效的视觉润色（间距、对比度、层级）→ skills/frontend-design/visual-hierarchy-refactoring

第 0 步 — 检查代码库，然后只询问尚不明确的事项

1. 搜索现有动效：transition、animation、@keyframes、framer-motion、motion.、react-spring、gsap、Tailwind 的 transition-*／animate-* 类。记录所有正在使用的时长和缓动——这里的不一致（例如悬停效果分别使用 150ms、200ms、250ms、300ms）通常是首先会发现的问题。
2. 检查是否有任何地方处理了 prefers-reduced-motion。如果没有，必须将其列为修复项。
3. 确定动画实现方式：如果项目已使用动效库，就用该库实现；否则默认使用 CSS 过渡／关键帧。对于 CSS 能实现的效果，绝不要引入动效库。
4. 找出缺少反馈的交互：没有悬停／激活状态的按钮、没有过渡效果便出现的模态框／Toast、突然弹出的表单错误。

向用户提问（一次性询问，仅限无法推断的内容）：期望的风格（沉稳／专业，还是活泼——如果产品领域显而易见，就据此推断）以及范围（审查整个应用，还是特定流程）。如果用户说“这个应用感觉很卡顿”，不要追问——进行审查，说明假设，然后继续。

工作流

1. 先编写动画规范

修改代码前先统一术语。标准时长类别：

类别	时长	缓动	适用对象
微交互反馈	150–250ms	ease-out	悬停、按下、聚焦、切换、颜色／状态变化
结构过渡	300–500ms	进入时 ease-out，退出时 ease-in	模态框、抽屉、页面、手风琴、Toast
注意力提示	500–1000ms	ease-in-out	提示、脉冲、单次强调
持续动画	循环约 1s	linear	旋转加载图标、不定进度条

决策规则：

• **按方向选择缓动：**进入的元素应减速（ease-out）；退出的元素应加速（ease-in）；屏幕内移动使用 ease-in-out；只有机械循环才使用 linear。诸如 cubic-bezier(0.34, 1.56, 0.64, 1) 的弹跳曲线仅用于刻意营造活泼感的场景——整个应用最多用一两处。
• **按尺寸和距离选择时长：**短距离移动的小元素使用时长范围的低端（悬停色调变化：150–200ms）；大面积表面或长距离移动使用高端（全屏抽屉：400–500ms）。工具提示和模态框不能使用相同的时长。
• 退出时长应短于进入时长（约为进入时长的 75%）——用户已经决定离开。
• 将第 0 步发现的不一致数值归并为最多 3–4 个命名令牌（例如 --duration-fast: 200ms; --duration-base: 300ms; --duration-slow: 450ms），并将其定义为 CSS 变量或主题令牌。

2. 使用四部分结构描述每种微交互

对于范围内的每种交互，请说明：触发条件（用户操作／系统事件）→ 规则（发生哪些变化、持续时间、缓动方式）→ 反馈（用户感知到什么）→ 循环与模式（是否重复、能否中断）。可中断性规则：对于用户可能快速切换的任何状态，基于状态的过渡（CSS transition 或动效库）都优于触发后不再响应的关键帧动画——半开的菜单必须平滑反向，而不是重新开始。

3. 在性能和无障碍约束下实现

• 只为 transform 和 opacity 添加动画（利于合成器处理）。绝不要直接为 width、height、top、left 或 box-shadow 添加动画；可通过交叉淡入伪元素的 opacity 来模拟阴影动画。小型控件可以为 background-color 添加动画。
• 在同一次改动中加入减少动态效果代码块——参见 references/patterns.md 中的基准实现。装饰性动效应消失；信息性动效（进度）可以仅以 opacity 保留。
• **反馈绝不能只依赖动效：**每次动画状态变化都要配合颜色／文本／图标变化，确保在减少动态效果时依然有效。
• **键盘操作效果一致：**每种 :hover 效果都要有对应的 :focus-visible 效果。
• 绝不可每秒闪烁超过 3 次（存在癫痫风险——这是 WCAG 要求，而非风格偏好）。

微反馈规范示例（完整示例集——包含按钮、表单验证、Toast、模态框、页面过渡——见 references/patterns.md）：

button {
  transition: background-color 200ms ease-out, transform 200ms ease-out;
}
button:hover:not(:disabled)  { background-color: var(--color-primary-dark); }
button:active:not(:disabled) { transform: scale(0.98); }
button:focus-visible         { outline: 2px solid var(--color-focus); outline-offset: 2px; }

4. 验证

尽可能运行应用（或推演渲染路径）：确认过渡效果正常触发、退出动画正常播放（常见疏漏——元素在退出动画播放前就已卸载）、快速切换不会卡顿或重新开始，并确认减少动态效果媒体查询确实会抑制移动效果。

必需的交付格式

交付以下两项：

1. 代码——使用项目现有的动效方案和令牌，实现过渡／动画。

2. 动画规范（markdown，作为项目的动效参考）：

## Motion tokens
| Token | Value | Easing | Used for |
| --duration-fast | 200ms | ease-out | hover, press, focus, toggles |
| --duration-base | 300ms | ease-out/ease-in | toasts, dropdowns, accordions |
| --duration-slow | 450ms | ease-out/ease-in | modals, drawers, page transitions |

## Interaction inventory
| Interaction | Trigger | Motion | Duration/easing | Status |
| Button hover | pointer/focus | bg tint + scale on press | fast / ease-out | implemented |
| Modal open | click | fade + 20px rise | slow / ease-out | implemented |
| Toast exit | timeout/dismiss | slide right + fade | base×0.75 / ease-in | implemented |

## Audit findings (for audit engagements)
| Issue | Location | Fix |
| 5 different hover durations | [files] | collapsed to --duration-fast |
| No reduced-motion support | global | baseline block added |

## Deliberately not animated
[List, with one-line reasons — restraint is part of the spec]

质量标准（交付前检查）

• 交付代码中的每个动画都有明确用途（确认／引导／说明）——如有疑问，能说出用途
• 所有时长均来自规范中的令牌；修改文件中不遗留任何魔法数字
• 进入动画 = 缓出，退出动画 = 缓入，循环动画 = 线性——如无明确说明，绝不例外
• 只为 transform／opacity 添加动画（小型控件的颜色变化除外）
• 存在有效的 prefers-reduced-motion 代码块
• 每种 :hover 状态都有对应的 :focus-visible 状态
• 动画状态变化也会改变颜色／文本／图标（动效不是唯一的信号）
• 闪烁频率不超过每秒 3 次；没有无限循环的装饰性动画

严禁事项：不得劫持滚动；不得在文本输入框中随按键添加动画；CSS 足以实现时，不得添加动效库；不得为布局属性添加动画。

集成

• skills/frontend-design/component-architecture → 提供本技能为其添加动画的组件状态（悬停／激活／加载中／禁用）；如果存在令牌系统，则在其中添加令牌。
• skills/frontend-design/loading-states → 决定显示哪种指示器；本技能为其提供闪烁／旋转／进度动效。
• skills/frontend-design/performance-optimization ← 使用规范中仅对合成器属性添加动画的约束；如果动画仍然掉帧，则反馈相关发现。
• skills/frontend-design/accessibility-excellence ← 审核交付内容是否符合减少动态效果和闪烁频率要求。

参考资料

• references/patterns.md — 完整实现示例集：完整的按钮状态、表单验证、骨架屏／旋转指示器／进度动效、Toast 进入／退出动画、页面和模态框过渡、减少动态效果基准代码块。编写实际 CSS 时请阅读。