emilkowal-animations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Emil Kowalski Animation Best Practices

Emil Kowalski 动画最佳实践

Comprehensive animation guide for web interfaces based on Emil Kowalski's teachings, open-source libraries (Sonner, Vaul), and his animations.dev course. Contains 43 rules across 7 categories, prioritized by impact.

基于Emil Kowalski的教学内容、开源库（Sonner、Vaul）以及他的animations.dev课程，这份指南是面向Web界面的全面动效指导。包含7个分类下的43条规则，按影响优先级排序。

When to Apply

适用场景

Reference these guidelines when:

Adding animations to React components
Choosing easing curves or timing values
Implementing gesture-based interactions (swipe, drag)
Building toast notifications or drawer components
Optimizing animation performance
Ensuring animation accessibility

在以下场景中参考本指南：

为React组件添加动画
选择缓动曲线或时长参数
实现基于手势的交互（滑动、拖拽）
构建提示框（toast）或抽屉组件
优化动画性能
确保动画的可访问性

Rule Categories by Priority

按优先级排序的规则分类


ease-
timing-
props-
transform-
interact-
strategy-
polish-

Priority	Category	Impact	Prefix
1	Easing Selection	CRITICAL	`ease-`
2	Timing & Duration	CRITICAL	`timing-`
3	Property Selection	HIGH	`props-`
4	Transform Techniques	HIGH	`transform-`
5	Interaction Patterns	MEDIUM-HIGH	`interact-`
6	Strategic Animation	MEDIUM	`strategy-`
7	Accessibility & Polish	MEDIUM	`polish-`


ease-
timing-
props-
transform-
interact-
strategy-
polish-

优先级	分类	影响程度	前缀
1	缓动选择	关键	`ease-`
2	时长与计时	关键	`timing-`
3	属性选择	高	`props-`
4	变换技巧	高	`transform-`
5	交互模式	中高	`interact-`
6	动效策略	中	`strategy-`
7	可访问性与细节优化	中	`polish-`

Quick Reference

快速参考

1. Easing Selection (CRITICAL)

1. 缓动选择（关键）

```
ease-out-default
```
- Use ease-out as your default easing
```
ease-custom-curves
```
- Use custom cubic-bezier over built-in CSS
```
ease-in-out-onscreen
```
- Use ease-in-out for on-screen movement
```
ease-spring-natural
```
- Use spring animations for natural motion
```
ease-ios-drawer
```
- Use iOS-style easing for drawer components
```
ease-context-matters
```
- Match easing to animation context

```
ease-out-default
```
- 使用ease-out作为默认缓动效果
```
ease-custom-curves
```
- 优先使用自定义cubic-bezier而非CSS内置缓动
```
ease-in-out-onscreen
```
- 屏幕内移动使用ease-in-out缓动
```
ease-spring-natural
```
- 使用弹簧动画实现自然动效
```
ease-ios-drawer
```
- 抽屉组件使用iOS风格缓动
```
ease-context-matters
```
- 缓动效果需匹配动画场景

2. Timing & Duration (CRITICAL)

2. 时长与计时（关键）

```
timing-300ms-max
```
- Keep UI animations under 300ms
```
timing-faster-better
```
- Faster animations improve perceived performance
```
timing-asymmetric
```
- Use asymmetric timing for press and release
```
timing-tooltip-delay
```
- Delay initial tooltips, instant subsequent ones
```
timing-drawer-500ms
```
- Use 500ms duration for drawer animations

```
timing-300ms-max
```
- UI动画时长不超过300ms
```
timing-faster-better
```
- 更快的动画提升感知性能
```
timing-asymmetric
```
- 按压和释放使用非对称时长
```
timing-tooltip-delay
```
- 首次提示框添加延迟，后续即时显示
```
timing-drawer-500ms
```
- 抽屉动画使用500ms时长

3. Property Selection (HIGH)

3. 属性选择（高）

```
props-transform-opacity
```
- Animate only transform and opacity
```
props-hardware-accelerated
```
- Use hardware-accelerated animations when main thread is busy
```
props-will-change
```
- Use will-change to prevent 1px shift
```
props-avoid-css-variables
```
- Avoid CSS variables for drag animations
```
props-clip-path-performant
```
- Use clip-path for layout-free reveals

```
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. Transform Techniques (HIGH)

4. 变换技巧（高）

```
transform-scale-097
```
- Scale buttons to 0.97 on press
```
transform-never-scale-zero
```
- Never animate from scale(0)
```
transform-percentage-translate
```
- Use percentage values for translateY
```
transform-origin-aware
```
- Make animations origin-aware
```
transform-scale-children
```
- Scale transforms affect children
```
transform-3d-preserve
```
- Use preserve-3d for 3D transform effects

```
transform-scale-097
```
- 按钮按压时缩放到0.97
```
transform-never-scale-zero
```
- 切勿从scale(0)开始动画
```
transform-percentage-translate
```
- translateY使用百分比值
```
transform-origin-aware
```
- 动画需考虑变换原点
```
transform-scale-children
```
- 缩放变换会影响子元素
```
transform-3d-preserve
```
- 使用preserve-3d实现3D变换效果

5. Interaction Patterns (MEDIUM-HIGH)

5. 交互模式（中高）

```
interact-interruptible
```
- Make animations interruptible
```
interact-momentum-dismiss
```
- Use momentum-based dismissal
```
interact-damping
```
- Damp drag at boundaries
```
interact-scroll-drag-conflict
```
- Resolve scroll and drag conflicts
```
interact-snap-points
```
- Implement velocity-aware snap points
```
interact-friction-upward
```
- Allow upward drag with friction
```
interact-pointer-capture
```
- Use pointer capture for drag operations

```
interact-interruptible
```
- 动画需支持中断
```
interact-momentum-dismiss
```
- 使用基于动量的关闭方式
```
interact-damping
```
- 边界处拖拽添加阻尼效果
```
interact-scroll-drag-conflict
```
- 解决滚动与拖拽的冲突
```
interact-snap-points
```
- 实现速度感知的吸附点
```
interact-friction-upward
```
- 允许带摩擦力的向上拖拽
```
interact-pointer-capture
```
- 拖拽操作使用指针捕获

6. Strategic Animation (MEDIUM)

6. 动效策略（中）

```
strategy-keyboard-no-animate
```
- Never animate keyboard-initiated actions
```
strategy-frequency-matters
```
- Consider interaction frequency before animating
```
strategy-purpose-required
```
- Every animation must have a purpose
```
strategy-feedback-immediate
```
- Provide immediate feedback on all actions
```
strategy-marketing-exception
```
- Marketing sites are the exception

```
strategy-keyboard-no-animate
```
- 切勿为键盘触发的操作添加动画
```
strategy-frequency-matters
```
- 添加动画前考虑交互频率
```
strategy-purpose-required
```
- 每个动画必须有明确目的
```
strategy-feedback-immediate
```
- 所有操作需提供即时反馈
```
strategy-marketing-exception
```
- 营销类网站除外

7. Accessibility & Polish (MEDIUM)

7. 可访问性与细节优化（中）

```
polish-reduced-motion
```
- Respect prefers-reduced-motion
```
polish-opacity-fallback
```
- Use opacity as reduced motion fallback
```
polish-framer-hook
```
- Use useReducedMotion hook in Framer Motion
```
polish-dont-remove-all
```
- Don't remove all animation for reduced motion
```
polish-blur-bridge
```
- Use blur to bridge animation states
```
polish-clip-path-tabs
```
- Use clip-path for tab transitions
```
polish-toast-stacking
```
- Implement toast stacking with scale and offset
```
polish-scroll-reveal
```
- Trigger scroll animations at appropriate threshold
```
polish-hover-gap-fill
```
- Fill gaps between hoverable elements
```
polish-stagger-children
```
- Stagger child animations for orchestration

```
polish-reduced-motion
```
- 尊重prefers-reduced-motion设置
```
polish-opacity-fallback
```
- 使用opacity作为减少动效的降级方案
```
polish-framer-hook
```
- 在Framer Motion中使用useReducedMotion钩子
```
polish-dont-remove-all
```
- 减少动效时不要移除所有动画
```
polish-blur-bridge
```
- 使用模糊效果衔接动画状态
```
polish-clip-path-tabs
```
- 使用clip-path实现标签页过渡
```
polish-toast-stacking
```
- 实现带缩放和偏移的提示框堆叠
```
polish-scroll-reveal
```
- 在合适的阈值触发滚动显示动画
```
polish-hover-gap-fill
```
- 填充可悬停元素间的间隙
```
polish-stagger-children
```
- 子元素动画使用 stagger 编排

Key Values Reference

关键参数参考

Value	Usage
`cubic-bezier(0.32, 0.72, 0, 1)`	iOS-style drawer/sheet animation
`scale(0.97)`	Button press feedback
`scale(0.95)`	Minimum enter scale (never scale(0))
`200ms ease-out`	Standard UI transition
`300ms`	Maximum duration for UI animations
`500ms`	Drawer animation duration
`0.11 px/ms`	Velocity threshold for momentum dismiss
`100px`	Scroll-reveal viewport threshold
`14px`	Toast stack offset

参数值	用途
`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`	提示框堆叠偏移量

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	分类定义与排序规则
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息