SwiftUI & AppKit Animation Best Practices

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.

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

Rule Categories by Priority

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-

Quick Reference

1. Timing Curves & Easing (CRITICAL)

• 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

2. Duration & Timing (CRITICAL)

• 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

3. Animation Properties (HIGH)

• 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

4. Transforms & Effects (HIGH)

• 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

5. Gesture & Interaction (HIGH)

• 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

6. Transitions & Navigation (MEDIUM-HIGH)

• 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

7. Scroll & Parallax (MEDIUM)

• 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

8. Strategic Animation (MEDIUM)

• 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

9. Accessibility & Polish (MEDIUM)

• 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

10. AppKit Specific (LOW-MEDIUM)

• 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

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

Concept Mapping (Web to 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)

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