emilkowal-animations-swift

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SwiftUI & AppKit Animation Best Practices

SwiftUI & AppKit 动画最佳实践

Comprehensive animation guide for Apple platform interfaces, adapted from Emil Kowalski's web animation principles and Framer Motion best practices. Contains 80 rules across 10 categories targeting iOS 17+, prioritized by impact.

这是一份针对苹果平台界面的综合动画指南，改编自Emil Kowalski的Web动画原则和Framer Motion最佳实践。包含针对iOS 17+的10个类别共80条规则，按影响优先级排序。

When to Apply

适用场景

Reference these guidelines when:

Adding animations to SwiftUI views
Choosing easing curves, springs, or timing values
Implementing gesture-based interactions (drag, tap, long press)
Building transitions and navigation animations
Using
```
matchedGeometryEffect
```
for shared element transitions
Creating scroll-linked or parallax effects
Using iOS 17+
```
PhaseAnimator
```
or
```
KeyframeAnimator
```
Optimizing animation performance
Ensuring animation accessibility with
```
accessibilityReduceMotion
```
Writing AppKit/macOS-specific animations

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

为SwiftUI视图添加动画
选择缓动曲线、弹簧效果或时间参数
实现基于手势的交互（拖拽、点击、长按）
构建转场与导航动画
使用
```
matchedGeometryEffect
```
实现共享元素转场
创建滚动联动或视差效果
使用iOS 17+的
```
PhaseAnimator
```
或
```
KeyframeAnimator
```
优化动画性能
通过
```
accessibilityReduceMotion
```
确保动画的可访问性
编写AppKit/macOS专属动画

Rule Categories by Priority

按优先级划分的规则类别


ease-
timing-
props-
transform-
gesture-
transition-
scroll-
strategy-
polish-
appkit-

Priority	Category	Impact	Prefix
1	Timing Curves & Easing	CRITICAL	`ease-`
2	Duration & Timing	CRITICAL	`timing-`
3	Animation Properties	HIGH	`props-`
4	Transforms & Effects	HIGH	`transform-`
5	Gesture & Interaction	HIGH	`gesture-`
6	Transitions & Navigation	MEDIUM-HIGH	`transition-`
7	Scroll & Parallax	MEDIUM	`scroll-`
8	Strategic Animation	MEDIUM	`strategy-`
9	Accessibility & Polish	MEDIUM	`polish-`
10	AppKit Specific	LOW-MEDIUM	`appkit-`


ease-
timing-
props-
transform-
gesture-
transition-
scroll-
strategy-
polish-
appkit-

优先级	类别	影响程度	前缀
1	时间曲线与缓动	关键	`ease-`
2	时长与时序	关键	`timing-`
3	动画属性	高	`props-`
4	变换与效果	高	`transform-`
5	手势与交互	高	`gesture-`
6	转场与导航	中高	`transition-`
7	滚动与视差	中	`scroll-`
8	动画策略	中	`strategy-`
9	可访问性与优化	中	`polish-`
10	AppKit专属	中低	`appkit-`

Quick Reference

快速参考

1. Timing Curves & Easing (CRITICAL)

1. 时间曲线与缓动（关键）

```
ease-prefer-easeout
```
- Use easeOut as your default easing
```
ease-avoid-linear
```
- Avoid linear easing for UI animations
```
ease-spring-default
```
- Prefer springs for natural motion
```
ease-spring-ios17
```
- Use iOS 17 Spring struct with bounce/duration
```
ease-custom-timing-curve
```
- Create custom curves with timingCurve
```
ease-ease-in-for-exits
```
- Use easeIn for exit animations
```
ease-ease-inout-for-emphasis
```
- Use easeInOut for emphasis motion
```
ease-spring-response
```
- Configure spring response for duration feel
```
ease-spring-damping
```
- Configure spring damping for bounce
```
ease-match-context
```
- Match easing to animation context

```
ease-prefer-easeout
```
- 默认使用easeOut缓动
```
ease-avoid-linear
```
- UI动画避免使用线性缓动
```
ease-spring-default
```
- 优先选择弹簧效果实现自然动效
```
ease-spring-ios17
```
- 使用iOS 17的Spring结构体配置弹跳/时长
```
ease-custom-timing-curve
```
- 用timingCurve创建自定义曲线
```
ease-ease-in-for-exits
```
- 退出动画使用easeIn缓动
```
ease-ease-inout-for-emphasis
```
- 强调动效使用easeInOut缓动
```
ease-spring-response
```
- 配置弹簧响应参数调整时长感受
```
ease-spring-damping
```
- 配置弹簧阻尼参数调整弹跳程度
```
ease-match-context
```
- 缓动效果需匹配动画场景

2. Duration & Timing (CRITICAL)

2. 时长与时序（关键）

```
timing-200ms-default
```
- Use 200ms as default UI animation duration
```
timing-100ms-micro
```
- Use 100ms for micro-interactions
```
timing-300ms-emphasis
```
- Keep emphasis animations under 300ms
```
timing-stagger-children
```
- Stagger child animations for orchestration
```
timing-delay-strategic
```
- Use delay strategically for sequencing

```
timing-200ms-default
```
- UI动画默认时长设为200ms
```
timing-100ms-micro
```
- 微交互动画使用100ms时长
```
timing-300ms-emphasis
```
- 强调动画时长控制在300ms以内
```
timing-stagger-children
```
- 子元素动画使用 stagger 实现编排
```
timing-delay-strategic
```
- 合理使用延迟实现动画序列

3. Animation Properties (HIGH)

3. 动画属性（高）

```
props-opacity-scale
```
- Prefer opacity and scale for performance
```
props-avoid-size-animate
```
- Avoid animating frame size directly
```
props-transform-origin
```
- Set anchor points for transforms
```
props-drawing-group
```
- Use drawingGroup for complex hierarchies
```
props-animation-disable
```
- Use animation(nil) to prevent animations
```
props-explicit-animation
```
- Use withAnimation for explicit control
```
props-implicit-animation
```
- Use .animation modifier for implicit animations

```
props-opacity-scale
```
- 优先使用透明度和缩放提升性能
```
props-avoid-size-animate
```
- 避免直接对帧尺寸做动画
```
props-transform-origin
```
- 为变换设置锚点
```
props-drawing-group
```
- 复杂层级使用drawingGroup
```
props-animation-disable
```
- 使用animation(nil)禁用动画
```
props-explicit-animation
```
- 使用withAnimation实现显式控制
```
props-implicit-animation
```
- 使用.animation修饰符实现隐式动画

4. Transforms & Effects (HIGH)

4. 变换与效果（高）

```
transform-scale-subtle
```
- Use subtle scale values (0.95-0.98)
```
transform-rotation-purposeful
```
- Apply rotation with purpose
```
transform-translate-direction
```
- Translate in meaningful directions
```
transform-3d-perspective
```
- Use rotation3DEffect for depth
```
transform-order-matters
```
- Modifier order affects output
```
transform-anchor-point
```
- Set anchor for rotation/scale origin
```
transform-combine-effects
```
- Combine transforms purposefully

```
transform-scale-subtle
```
- 使用细微缩放值（0.95-0.98）
```
transform-rotation-purposeful
```
- 有目的性地应用旋转
```
transform-translate-direction
```
- 按有意义的方向进行位移
```
transform-3d-perspective
```
- 使用rotation3DEffect实现深度感
```
transform-order-matters
```
- 修饰符顺序会影响输出结果
```
transform-anchor-point
```
- 为旋转/缩放设置原点锚点
```
transform-combine-effects
```
- 有目的性地组合多种变换

5. Gesture & Interaction (HIGH)

5. 手势与交互（高）

```
gesture-tap-feedback
```
- Provide immediate tap feedback
```
gesture-long-press
```
- Animate long press states
```
gesture-drag-basic
```
- Implement smooth drag interactions
```
gesture-drag-constraints
```
- Constrain drag within bounds
```
gesture-drag-velocity
```
- Use velocity for momentum effects
```
gesture-gesture-state
```
- Use @GestureState for transient values
```
gesture-updating-modifier
```
- Use .updating for live feedback
```
gesture-simultaneous-vs-exclusive
```
- Choose gesture composition
```
gesture-magnify-gesture
```
- Implement pinch-to-zoom
```
gesture-rotation-gesture
```
- Implement rotation gestures
```
gesture-hover-macos
```
- Handle hover on macOS
```
gesture-sensory-feedback
```
- Pair gestures with haptics
```
gesture-spring-on-release
```
- Spring back on gesture end
```
gesture-cancellation
```
- Handle gesture cancellation gracefully

```
gesture-tap-feedback
```
- 提供即时的点击反馈
```
gesture-long-press
```
- 为长按状态添加动画
```
gesture-drag-basic
```
- 实现流畅的拖拽交互
```
gesture-drag-constraints
```
- 限制拖拽范围在边界内
```
gesture-drag-velocity
```
- 利用速度实现动量效果
```
gesture-gesture-state
```
- 使用@GestureState存储临时值
```
gesture-updating-modifier
```
- 使用.updating实现实时反馈
```
gesture-simultaneous-vs-exclusive
```
- 选择合适的手势组合方式
```
gesture-magnify-gesture
```
- 实现捏合缩放
```
gesture-rotation-gesture
```
- 实现旋转手势
```
gesture-hover-macos
```
- 在macOS上处理悬停事件
```
gesture-sensory-feedback
```
- 为手势搭配触觉反馈
```
gesture-spring-on-release
```
- 手势结束时使用弹簧效果复位
```
gesture-cancellation
```
- 优雅处理手势取消

6. Transitions & Navigation (MEDIUM-HIGH)

6. 转场与导航（中高）

```
transition-builtin-types
```
- Use built-in transition types
```
transition-asymmetric
```
- Use asymmetric for different enter/exit
```
transition-combined
```
- Combine transitions for richer effects
```
transition-custom-modifier
```
- Create custom transition modifiers
```
transition-matched-geometry
```
- Use matchedGeometryEffect properly
```
transition-namespace-scope
```
- Manage @Namespace lifecycle
```
transition-navigation-transitions
```
- Customize navigation transitions
```
transition-sheet-presentations
```
- Animate sheet presentations
```
transition-id-for-replacement
```
- Use .id() for view replacement
```
transition-content-transition
```
- Use contentTransition for text

```
transition-builtin-types
```
- 使用内置转场类型
```
transition-asymmetric
```
- 为进入/退出使用不对称转场
```
transition-combined
```
- 组合多种转场实现更丰富的效果
```
transition-custom-modifier
```
- 创建自定义转场修饰符
```
transition-matched-geometry
```
- 正确使用matchedGeometryEffect
```
transition-namespace-scope
```
- 管理@Namespace生命周期
```
transition-navigation-transitions
```
- 自定义导航转场
```
transition-sheet-presentations
```
- 为弹窗展示添加动画
```
transition-id-for-replacement
```
- 使用.id()实现视图替换动画
```
transition-content-transition
```
- 为文本使用contentTransition

7. Scroll & Parallax (MEDIUM)

7. 滚动与视差（中）

```
scroll-geometry-reader
```
- Use GeometryReader for scroll position
```
scroll-preference-key
```
- Use PreferenceKey for scroll data
```
scroll-parallax-effect
```
- Create parallax scroll effects
```
scroll-sticky-header
```
- Implement animated sticky headers
```
scroll-scroll-transition
```
- Use iOS 17 scrollTransition modifier
```
scroll-visual-effect
```
- Use iOS 17 visualEffect modifier

```
scroll-geometry-reader
```
- 使用GeometryReader获取滚动位置
```
scroll-preference-key
```
- 使用PreferenceKey获取滚动数据
```
scroll-parallax-effect
```
- 创建滚动视差效果
```
scroll-sticky-header
```
- 实现带动画的粘性头部
```
scroll-scroll-transition
```
- 使用iOS 17的scrollTransition修饰符
```
scroll-visual-effect
```
- 使用iOS 17的visualEffect修饰符

8. Strategic Animation (MEDIUM)

8. 动画策略（中）

```
strategy-purposeful-motion
```
- Every animation needs purpose
```
strategy-hierarchy-emphasis
```
- Use motion to show hierarchy
```
strategy-state-communication
```
- Animate state changes clearly
```
strategy-spatial-continuity
```
- Maintain spatial relationships
```
strategy-brand-expression
```
- Express brand through motion

```
strategy-purposeful-motion
```
- 每一个动画都要有明确目的
```
strategy-hierarchy-emphasis
```
- 用动效展示层级关系
```
strategy-state-communication
```
- 通过动画清晰展示状态变化
```
strategy-spatial-continuity
```
- 保持空间关系的连续性
```
strategy-brand-expression
```
- 通过动效传递品牌调性

9. Accessibility & Polish (MEDIUM)

9. 可访问性与优化（中）

```
polish-reduce-motion
```
- Respect accessibilityReduceMotion
```
polish-phase-animator
```
- Use PhaseAnimator for sequences
```
polish-keyframe-animator
```
- Use KeyframeAnimator for complex paths
```
polish-animation-completions
```
- Handle animation completion
```
polish-interruptible-animations
```
- Make animations interruptible
```
polish-animation-debugging
```
- Debug animations effectively
```
polish-performance-profiling
```
- Profile animation performance
```
polish-symbol-effects
```
- Use SF Symbol effects
```
polish-text-animations
```
- Animate text with contentTransition
```
polish-haptic-pairing
```
- Pair animations with haptic feedback

```
polish-reduce-motion
```
- 尊重accessibilityReduceMotion设置
```
polish-phase-animator
```
- 使用PhaseAnimator实现序列动画
```
polish-keyframe-animator
```
- 使用KeyframeAnimator实现复杂路径动画
```
polish-animation-completions
```
- 处理动画完成事件
```
polish-interruptible-animations
```
- 让动画可被中断
```
polish-animation-debugging
```
- 高效调试动画
```
polish-performance-profiling
```
- 分析动画性能
```
polish-symbol-effects
```
- 使用SF Symbol效果
```
polish-text-animations
```
- 用contentTransition为文本添加动画
```
polish-haptic-pairing
```
- 为动画搭配触觉反馈

10. AppKit Specific (LOW-MEDIUM)

10. AppKit专属（中低）

```
appkit-nsanimation-context
```
- Use NSAnimationContext for grouping
```
appkit-core-animation
```
- Use Core Animation layers
```
appkit-layer-backed-views
```
- Enable layer backing for performance
```
appkit-implicit-animations
```
- Leverage implicit layer animations
```
appkit-spring-animation
```
- Create spring animations in AppKit
```
appkit-animator-proxy
```
- Use animator proxy for view animations

```
appkit-nsanimation-context
```
- 使用NSAnimationContext进行动画分组
```
appkit-core-animation
```
- 使用Core Animation图层
```
appkit-layer-backed-views
```
- 启用图层提升性能
```
appkit-implicit-animations
```
- 利用图层隐式动画
```
appkit-spring-animation
```
- 在AppKit中创建弹簧动画
```
appkit-animator-proxy
```
- 使用animator代理实现视图动画

Key Values Reference

关键参数参考

Value	Usage
`.spring(duration: 0.3, bounce: 0.2)`	Standard iOS 17 spring animation
`.spring(response: 0.3, dampingFraction: 0.7)`	Classic spring configuration
`.easeOut(duration: 0.2)`	Standard UI transition
`scaleEffect(0.97)`	Button press feedback
`scaleEffect(0.95)`	Minimum enter scale (never scale to 0)
`0.2` seconds	Default micro-interaction duration
`0.3` seconds	Maximum duration for UI animations
`0.5` seconds	Sheet/drawer animation duration

参数	用途
`.spring(duration: 0.3, bounce: 0.2)`	标准iOS 17弹簧动画
`.spring(response: 0.3, dampingFraction: 0.7)`	经典弹簧配置
`.easeOut(duration: 0.2)`	标准UI转场动画
`scaleEffect(0.97)`	按钮按下反馈
`scaleEffect(0.95)`	最小进入缩放值（切勿缩放到0）
`0.2` 秒	默认微交互动画时长
`0.3` 秒	UI动画最大时长
`0.5` 秒	弹窗/抽屉动画时长

Concept Mapping (Web to SwiftUI)

概念映射（Web → SwiftUI）

Web Concept	SwiftUI Equivalent
`ease-out`	`.easeOut` or `Animation.easeOut(duration:)`
`cubic-bezier(a,b,c,d)`	`.timingCurve(a, b, c, d, duration:)`
Framer Motion spring	`.spring(duration:bounce:)` (iOS 17+)
`transform: scale(0.97)`	`.scaleEffect(0.97)`
`transform-origin`	`.scaleEffect(anchor: .topLeading)`
`useMotionValue`	`@State` / `@GestureState`
`AnimatePresence`	`.transition()` + `.id()`
`layoutId`	`.matchedGeometryEffect(id:in:)`
`useScroll`	`GeometryReader` + `PreferenceKey`
`whileHover/whileTap`	`.onHover {}` / gesture modifiers
`dragConstraints`	`DragGesture` with `onChange` bounds
`prefers-reduced-motion`	`@Environment(\.accessibilityReduceMotion)`

Web概念	SwiftUI对应实现
`ease-out`	`.easeOut` 或 `Animation.easeOut(duration:)`
`cubic-bezier(a,b,c,d)`	`.timingCurve(a, b, c, d, duration:)`
Framer Motion spring	`.spring(duration:bounce:)` (iOS 17+)
`transform: scale(0.97)`	`.scaleEffect(0.97)`
`transform-origin`	`.scaleEffect(anchor: .topLeading)`
`useMotionValue`	`@State` / `@GestureState`
`AnimatePresence`	`.transition()` + `.id()`
`layoutId`	`.matchedGeometryEffect(id:in:)`
`useScroll`	`GeometryReader` + `PreferenceKey`
`whileHover/whileTap`	`.onHover {}` / 手势修饰符
`dragConstraints`	`DragGesture` 配合 `onChange` 限制边界
`prefers-reduced-motion`	`@Environment(\.accessibilityReduceMotion)`

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	版本与参考信息