emilkowal-animations-swift

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 86 rules across 10 categories targeting iOS 17+, prioritized by impact.

Review Format (Required)

When reviewing UI animation code, you MUST use a markdown table with Before/After/Why columns. Do NOT use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table like this:

Before	After	Why
.animation(.default)	.animation(.easeOut(duration: 0.2))	Specify explicit easing; avoid default
scaleEffect(0)	scaleEffect(0.95) with .opacity(0)	Nothing in the real world appears from nothing
.easeIn on dropdown	.easeOut(duration: 0.2)	easeIn feels sluggish; easeOut gives instant feedback
No press feedback on button	scaleEffect(isPressed ? 0.97 : 1.0)	Buttons must feel responsive to press
.scaleEffect(anchor: .center) on popover	.scaleEffect(anchor: .top) matching trigger	Popovers should scale from their trigger, not center

One row per issue found. The "Why" column briefly explains the reasoning.

Review Checklist

When reviewing SwiftUI animation code, check for these issues:

Issue	Fix
.animation(.default) or no explicit curve	Specify exact easing: .easeOut(duration: 0.2) or .spring(duration: 0.3)
scaleEffect(0) entry animation	Start from scaleEffect(0.95) with .opacity(0)
.easeIn on entering UI element	Switch to .easeOut or .spring()
.scaleEffect(anchor: .center) on popover	Set anchor to match trigger location (modals are exempt)
Animation on keyboard-initiated action	Remove animation entirely — use instant state change
Duration > 300ms on UI element	Reduce to 150-250ms or use spring
Hover animation without #if os(macOS) guard	Gate behind platform check or .onHover availability
withAnimation wrapping high-frequency action	Remove — actions triggered 100+/day should be instant
Animating .frame() or .padding()	Use .scaleEffect, .offset, .opacity instead (GPU-accelerated)
Same enter/exit transition speed	Make exit faster: .asymmetric(insertion: 0.3s, removal: 0.15s)
Elements all appear at once	Add stagger delay (30-80ms between items)
Manual Timer/CADisplayLink animation loop	Use .animation() or withAnimation (runs on render server)
Missing accessibilityReduceMotion check	Add @Environment(\.accessibilityReduceMotion) guard
No press feedback on tappable element	Add scaleEffect(0.97) on press via ButtonStyle

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
• transform-blur-crossfade - Use blur to mask imperfect crossfades

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
• gesture-asymmetric-press-release - Asymmetric press/release timing

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
• strategy-frequency-framework - Decide by usage frequency before animating
• strategy-no-keyboard-animation - Never animate keyboard-initiated actions
• strategy-component-design - Component design principles for loved libraries

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
• polish-skip-subsequent-delays - Skip delay on subsequent tooltips/popovers

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