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

| API | Minimum Version | Reference |

|-----|----------------|-----------|

| withAnimation | iOS 13 | core-animations.md |

| .animation(_:value:) | iOS 13 | core-animations.md |

| .spring(response:dampingFraction:) | iOS 13 | core-animations.md |

| .matchedGeometryEffect | iOS 14 | transitions.md |

| .transition(.push(from:)) | iOS 16 | transitions.md |

| .contentTransition(.numericText()) | iOS 16 | transitions.md |

| PhaseAnimator | iOS 17 | phase-keyframe-animators.md |

| KeyframeAnimator | iOS 17 | phase-keyframe-animators.md |

| .spring(duration:bounce:) | iOS 17 | core-animations.md |

| Spring presets (.bouncy, .snappy, .smooth) | iOS 17 | core-animations.md |

| withAnimation(_:completionCriteria:_:completion:) | iOS 17 | core-animations.md |

| .symbolEffect() | iOS 17 | symbol-effects.md |

| .transition(.blurReplace) | iOS 17 | transitions.md |

| .contentTransition(.symbolEffect(.replace)) | iOS 17 | transitions.md |

| Transition protocol / TransitionPhase | iOS 17 | transitions.md |

| TransactionKey, scoped .animation / .transaction variants | iOS 17 | core-animations.md |

| KeyframeTimeline, .mapCameraKeyframeAnimator | iOS 17 | phase-keyframe-animators.md |

| .scrollTransition, .visualEffect | iOS 17 | visual-effects.md |

| Shaders: .colorEffect / .distortionEffect / .layerEffect | iOS 17 | visual-effects.md |

| MeshGradient | iOS 18 | visual-effects.md |

| TextRenderer / TextAttribute | iOS 18 | visual-effects.md |

| .matchedTransitionSource | iOS 18 | transitions.md |

| .navigationTransition(.zoom) — push, sheet, fullScreenCover | iOS 18 | transitions.md |

| UIViewController.preferredTransition = .zoom | iOS 18 | transitions.md |

| UIView.animate(_: Animation) / context.animate | iOS 18 | transitions.md |

Top 5 Mistakes — Quick Reference

| # | Mistake | Fix | Details |

|---|---------|-----|---------|

| 1 | spring(response:bounce:) — mixing parameter generations | Use either spring(response:dampingFraction:) (iOS 13) or spring(duration:bounce:) (iOS 17) | core-animations.md |

| 2 | .animation(.spring()) without value: parameter | Always pass value: — the no-value variant is deprecated (iOS 15) | core-animations.md |

| 3 | Wrong PhaseAnimator closure signature | PhaseAnimator(phases) { content, phase in } — not { phase in } | phase-keyframe-animators.md |

| 4 | Using matchedGeometryEffect for NavigationStack transitions | Use matchedTransitionSource + .navigationTransition(.zoom) on iOS 18+ | transitions.md |

| 5 | Using withAnimation for SF Symbol effects | Use .symbolEffect() modifier instead | symbol-effects.md |

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

| File | Content |

|------|---------|

| [core-animations.md](core-animations.md) | withAnimation, springs, completions, transactions + TransactionKey, timing curves, Animatable mechanics, fluid-interface principles (momentum projection, rubber-banding, hysteresis) |

| [phase-keyframe-animators.md](phase-keyframe-animators.md) | PhaseAnimator, KeyframeAnimator, KeyframeTimeline, MapKit camera keyframes, custom animations |

| [transitions.md](transitions.md) | View transitions, custom Transition protocol, matched geometry, navigation/zoom transitions (SwiftUI + UIKit), interruptibility, UIKit↔SwiftUI bridging, gesture-driven springs |

| [symbol-effects.md](symbol-effects.md) | SF Symbol effects, accessibility |

| [visual-effects.md](visual-effects.md) | scrollTransition, visualEffect, MeshGradient, TextRenderer, shader effects (colorEffect/distortionEffect/layerEffect), effect pipelines, semantic alignment guides |