emilkowal-animations

Emil Kowalski 动画最佳实践

基于 Emil Kowalski 的经验、开源库（Sonner、Vaul）及其 animations.dev 课程编写的 Web 界面动画综合指南。涵盖 8 个类别中的 58 条规则，并按影响程度排序。

适用场景

在以下情况下参考这些指南：

• 为 React 组件添加动画
• 选择缓动曲线或时间值
• 实现基于手势的交互（滑动、拖拽）
• 构建 toast 通知或抽屉组件
• 优化动画性能
• 确保动画的无障碍性
• 使用 Tailwind CSS v4 工具类实现上述任意效果（参见 tw- 类别）

按优先级排列的规则类别

优先级	类别	影响程度	前缀
1	缓动选择	CRITICAL	ease-
2	时间与时长	CRITICAL	timing-
3	属性选择	HIGH	props-
4	变换技巧	HIGH	transform-
5	交互模式	MEDIUM-HIGH	interact-
6	策略性动画	MEDIUM	strategy-
7	无障碍性与润色	MEDIUM	polish-
8	Tailwind v4 工具类	MEDIUM	tw-

快速参考

1. 缓动选择（CRITICAL）

• ease-out-default - 默认使用 ease-out 缓动
• ease-custom-curves - 使用自定义 cubic-bezier，而非内置 CSS 缓动
• ease-in-out-onscreen - 对屏幕上的移动使用 ease-in-out
• ease-spring-natural - 使用弹簧动画实现自然运动
• ease-spring-config - 配置弹簧动画的时长和弹性
• ease-ios-drawer - 抽屉组件使用 iOS 风格的缓动
• ease-context-matters - 根据动画场景选择合适的缓动

2. 时间与时长（CRITICAL）

• timing-300ms-max - UI 动画时长控制在 300ms 以内
• timing-faster-better - 更快的动画能提升感知性能
• timing-asymmetric - 按下和释放时使用非对称时长
• timing-tooltip-delay - 首次显示 tooltip 时延迟，之后立即显示
• timing-drawer-500ms - 抽屉动画使用 500ms 时长

3. 属性选择（HIGH）

• props-transform-opacity - 仅对 transform 和 opacity 设置动画
• props-hardware-accelerated - 主线程繁忙时使用硬件加速动画
• props-will-change - 使用 will-change 防止 1px 偏移
• props-avoid-css-variables - 拖拽动画避免使用 CSS 变量
• props-clip-path-performant - 使用 clip-path 实现不影响布局的显现效果

4. 变换技巧（HIGH）

• transform-scale-097 - 按下按钮时将其缩放至 0.97
• transform-never-scale-zero - 绝不从 scale(0) 开始动画
• transform-percentage-translate - translateY 使用百分比值
• transform-origin-aware - 根据变换原点调整动画
• transform-scale-children - 缩放变换会影响子元素
• transform-3d-preserve - 3D 变换效果使用 preserve-3d
• transform-starting-style - 使用 @starting-style 为进入状态添加动画

5. 交互模式（中高）

• interact-interruptible - 让动画可中断
• interact-momentum-dismiss - 使用基于惯性的关闭方式
• interact-damping - 在边界处为拖动添加阻尼
• interact-scroll-drag-conflict - 解决滚动与拖动冲突
• interact-snap-points - 实现感知速度的吸附点
• interact-friction-upward - 允许向上拖动并添加摩擦力
• interact-pointer-capture - 在拖动操作中使用指针捕获
• interact-multitouch - 拖动时忽略额外的触摸点
• interact-touch-hover - 通过指针媒体查询控制悬停动画

6. 动画策略（中）

• strategy-keyboard-no-animate - 绝不为键盘触发的操作添加动画
• strategy-frequency-matters - 添加动画前考虑交互频率
• strategy-purpose-required - 每个动画都必须有明确目的
• strategy-feedback-immediate - 对所有操作提供即时反馈
• strategy-marketing-exception - 营销网站是例外
• strategy-cohesion - 让动效符合组件的个性
• strategy-review-fresh-eyes - 慢动作回看动画，并在次日再次审视

7. 无障碍与润色（中）

• polish-reduced-motion - 遵循 prefers-reduced-motion 设置
• polish-opacity-fallback - 使用透明度作为减少动态效果时的回退方案
• polish-framer-hook - 在 Framer Motion 中使用 useReducedMotion Hook
• polish-dont-remove-all - 减少动态效果时仍保留柔和动画
• polish-blur-bridge - 使用模糊效果衔接动画状态
• polish-clip-path-tabs - 使用 clip-path 实现标签页切换过渡
• polish-toast-stacking - 使用缩放和偏移实现 Toast 堆叠
• polish-scroll-reveal - 在适当的阈值触发滚动动画
• polish-hover-gap-fill - 填补可悬停元素之间的空隙
• polish-stagger-children - 错开子元素动画以实现编排

8. Tailwind v4 工具类（中等）

使用合适的 Tailwind CSS v4 工具类来表达上述原则。仅适用于 Tailwind v4 项目；上述原生 CSS 和 Framer Motion 规则仍是权威依据。

• tw-ease-duration-defaults - 显式设置 ease-out 和小于 300ms 的持续时间
• tw-custom-easing-theme - 将自定义缓动曲线注册为 @theme 令牌
• tw-press-scale - 使用 active:scale-[0.97] 提供按钮按压反馈
• tw-asymmetric-timing - 使用 active:duration 分别设置按压和释放的时长
• tw-starting-enter - 使用 starting: 变体为进入状态添加动画
• tw-reduced-motion - 使用 motion-safe / motion-reduce 控制是否启用移动效果
• tw-origin-aware - 使用 origin-* 工具类设置变换原点
• tw-will-change - 仅在活动手势期间应用 will-change-transform

关键值参考

值	用途
cubic-bezier(0.23, 1, 0.32, 1)	UI 交互的强缓出效果
cubic-bezier(0.77, 0, 0.175, 1)	屏幕内移动的强缓入缓出效果
cubic-bezier(0.32, 0.72, 0, 1)	iOS 风格抽屉/面板动画
scale(0.97)	按钮按压反馈
scale(0.95)	最小进入缩放比例（绝不使用 scale(0)）
200ms ease-out	标准 UI 过渡效果
300ms	UI 动画的最长持续时间
500ms	抽屉动画持续时间
0.11 px/ms	惯性关闭的速度阈值
100px	滚动显现的视口阈值
14px	Toast 堆叠偏移量

按元素设置持续时间

根据元素的出现频率和移动幅度选择持续时间。UI 动画应控制在 300ms 以内。

元素	持续时间
按钮按压反馈	100–160ms
工具提示、小型弹出框	125–200ms
下拉菜单、选择框	150–250ms
模态框、抽屉	200–500ms
营销 / 说明内容	可以更长

参考文件

文件	说明
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息