Animation Patterns

Animation Patterns

Correct API shapes and patterns for SwiftUI animations. Prevents the most common mistakes: mixed spring parameter generations, wrong PhaseAnimator/KeyframeAnimator closure signatures, and using matchedGeometryEffect where matchedTransitionSource is needed.

When This Skill Activates

Use this skill when the user:

• Asks to add, fix, or review animation code
• Mentions spring, bounce, or snappy animations
• Wants view transitions (insertion/removal, hero, zoom)
• Asks about PhaseAnimator or KeyframeAnimator
• Wants SF Symbol effects (bounce, pulse, wiggle, breathe)
• Mentions matchedGeometryEffect or matchedTransitionSource
• Asks about reduce motion / animation accessibility
• Wants to sequence or chain animations
• Mentions withAnimation, animation completions, or Transaction
• Wants scroll-driven effects (parallax, carousels, scrollTransition, visualEffect)
• Mentions MeshGradient, TextRenderer, or Metal shader effects (colorEffect, distortionEffect, layerEffect)

Decision Tree

Choose the right reference file based on what the user needs:

What are you animating?│├─ A state change (opacity, position, color)│  └─ → core-animations.md│     ├─ withAnimation { } — explicit animation│     ├─ .animation(_:value:) — implicit animation│     └─ Spring configuration — .spring, .bouncy, .snappy, .smooth│├─ A multi-step / sequenced animation│  └─ → phase-keyframe-animators.md (PhaseAnimator)│     └─ Cycles through discrete phases automatically or on trigger│├─ A complex multi-property animation (scale + rotation + offset)│  └─ → phase-keyframe-animators.md (KeyframeAnimator)│     └─ Timeline-based keyframes with per-property tracks│├─ A view appearing / disappearing│  └─ → transitions.md│     ├─ .transition() — insertion/removal│     ├─ .contentTransition() — text/symbol changes│     └─ .asymmetric() — different in/out│├─ A hero / zoom navigation transition│  └─ → transitions.md (matchedTransitionSource section)│     ├─ iOS 18+: matchedTransitionSource + .navigationTransition(.zoom)│     ├─ UIKit: preferredTransition = .zoom (capture stable IDs, never views)│     └─ iOS 14+: matchedGeometryEffect (NOT for NavigationStack)│├─ A UIKit view driven by SwiftUI state or gestures│  └─ → transitions.md (Bridging UIKit and SwiftUI Animations)│     └─ UIView.animate(.spring(...)) / context.animate in updateUIView│├─ An SF Symbol animation│  └─ → symbol-effects.md│     └─ .symbolEffect(.bounce), .pulse, .wiggle, .breathe, .rotate│├─ A scroll-driven, geometry-driven, or shader effect│  └─ → visual-effects.md│     ├─ .scrollTransition — carousel scale/parallax/caption fades│     ├─ .visualEffect — position-based effects without GeometryReader│     ├─ MeshGradient — animatable multi-point gradients│     ├─ TextRenderer — per-line / per-glyph text animation│     └─ ShaderLibrary + .colorEffect / .distortionEffect / .layerEffect│└─ Spring physics / timing configuration   └─ → core-animations.md (Spring Configurations section)

API Availability

Top 5 Mistakes — Quick Reference

Review Checklist

When reviewing animation code, verify:

• Reduce motion — animations respect AccessibilityMotionEffect or UIAccessibility.isReduceMotionEnabled; provide non-motion alternatives
• Duration limits — no animation exceeds ~0.5s for UI feedback; longer only for decorative/ambient effects
• Spring vs linear — springs for interactive/physical motion; linear/easeInOut only for opacity fades or progress indicators
• No deprecated APIs — .animation(.spring()) without value: is deprecated; .animation(nil) is replaced by withTransaction
• Correct spring generation — parameter names match the same API generation (never mix response with bounce)
• Completion handlers — using withAnimation(_:completionCriteria:_:completion:) (iOS 17+), not inventing .onAnimationCompleted
• Transition scope — .transition() only affects views inside if/switch controlled by state; not for views that are always present
• Per-frame closures stay cheap — KeyframeAnimator content closures, visualEffect closures, TextRenderer.draw, and Animatable view bodies run every frame; no allocation, formatting, or layout math inside

Reference Files