iOS Animation Implementation

• The system doesn't provide the spatial relationship you need (hero transitions, custom gestures)
• You need coordinated multi-property choreography
• The animation is a signature moment that defines the app's identity
• Gesture-driven interaction requires custom progress mapping

API Selection

Choose the right API for the job. Start with SwiftUI animations (simplest, most declarative), drop to UIKit when you need interactive control, and reach for Core Animation only when you need layer-level precision.

Implementation by Category

Detailed patterns and code examples live in the reference files. Load the one that matches your task:

When to Load References

• Writing withAnimation, spring parameters, PhaseAnimator, or KeyframeAnimator → swiftui-animations.md
• Building navigation transitions, modal presentations, matchedGeometryEffect, or custom Transition → transitions.md
• Implementing drag-to-dismiss, swipe actions, pinch/rotate, or scroll-linked effects → gesture-animations.md
• Working with CABasicAnimation, UIViewPropertyAnimator, layer animations, or bridging SwiftUI↔UIKit → core-animation.md

Spring Parameters Quick Reference

Springs are the default animation type in modern SwiftUI. Use duration and bounce — not mass/stiffness/damping unless bridging to UIKit/CA.

Accessibility & Multimodal Feedback

Apple's HIG: "Make motion optional" and "supplement visual feedback by also using alternatives like haptics and audio to communicate." Every animation must handle Reduce Motion, and important state changes should use multiple feedback channels — not animation alone.

@Environment(\.accessibilityReduceMotion) private var reduceMotion

// Pattern 1: Conditional animation
withAnimation(reduceMotion ? .none : .spring()) {
    isExpanded.toggle()
}

// Pattern 2: Simplified alternative
.animation(reduceMotion ? .easeOut(duration: 0.15) : .spring(duration: 0.5, bounce: 0.3), value: isActive)

// Pattern 3: Skip entirely
if !reduceMotion {
    view.phaseAnimator(phases) { /* ... */ }
}

Reduce Motion fallback options (from most to least graceful):

1. Crossfade — replace motion with opacity transition
2. Shortened — same animation, much faster (0.1–0.15s), no bounce
3. Instant — .animation(.none) or skip the animation block entirely

Cancellation & Interruptibility

Apple's HIG: "Don't make people wait for an animation to complete before they can do anything, especially if they have to experience the animation more than once." Every animation must be interruptible.

• Spring animations retarget automatically — this is the default and almost always what you want
• For gesture-driven animations, the user is always in control — let them cancel mid-flight
• For sequenced animations (KeyframeAnimator, PhaseAnimator with trigger), ensure the UI remains interactive during playback
• Never disable user interaction during an animation unless there's a critical reason (e.g., destructive action confirmation)

Performance Checklist

• Animate on the render server when possible — Core Animation runs off the main thread, SwiftUI's drawingGroup() moves rendering to Metal
• Avoid animating view identity changes (.id() modifier) — this destroys and recreates the view
• Use geometryGroup() when parent geometry changes cause child layout anomalies during animation
• Provide explicit shadowPath when animating shadows — without it, the system recalculates the path every frame
• In lists and scroll views, avoid per-item blur/shadow animations — these cause offscreen rendering for each cell
• Keep PhaseAnimator and looping animations lightweight — they run continuously
• For frequent interactions, prefer system-provided animation over custom motion — Apple's HIG: "generally avoid adding motion to UI interactions that occur frequently"
• Profile with Instruments → "Animation Hitches" template to find frame drops