dot-skills iOS SwiftUI Animations Best Practices

Comprehensive animation guidelines for SwiftUI apps, designed to produce fluid, native-feeling motion that matches Apple's first-party quality. Contains 47 rules across 8 categories, prioritized by impact — from spring physics fundamentals to orchestration polish.

When to Apply

Reference these guidelines when:

• Adding animations to SwiftUI views or transitions
• Building gesture-driven interactions (drag, swipe, pan)
• Connecting views with spatial transitions (expand/collapse, navigation morphs)
• Designing micro-interactions (button press, toggle, loading states)
• Making content changes feel physical (number rolls, symbol replacements)
• Choreographing multi-element animation sequences
• Reviewing animation code for performance and accessibility

Rule Categories by Priority

Quick Reference

1. Spring Physics (CRITICAL)

• spring-smooth-default — Default to .smooth spring for all UI transitions
• spring-snappy-responsive — Use .snappy spring for responsive interactions
• spring-bouncy-celebration — Use .bouncy spring for playful and celebratory moments
• spring-custom-parameters — Tune custom springs with response and dampingFraction
• spring-velocity-preservation — Springs preserve velocity on interruption
• spring-never-linear — Never use linear or easeInOut for interactive UI
• spring-completion-chaining — Use withAnimation completion for chained sequences

2. Timing & Feel (CRITICAL)

• feel-250ms-max — Keep UI animations under 250ms
• feel-faster-better — Faster animations almost always feel better
• feel-asymmetric-enter-exit — Use asymmetric timing for enter and exit
• feel-distance-proportional — Match duration to distance traveled
• feel-haptic-sync — Sync haptic feedback to visual animation keyframes
• feel-stagger-timing — Stagger reveals at 30-50ms intervals

3. Gesture Continuity (HIGH)

• gesture-rubber-band — Rubber band at drag boundaries
• gesture-momentum-dismiss — Dismiss on velocity OR distance threshold
• gesture-snap-points — Use velocity-aware snap points
• gesture-interruptible — Make all gesture animations interruptible
• gesture-scroll-drag-conflict — Resolve scroll and drag gesture conflicts
• gesture-state-transient — Use GestureState for transient drag state
• gesture-projected-landing — Project gesture velocity for natural landing position

4. Spatial Transitions (HIGH)

• spatial-matched-geometry — Use matchedGeometryEffect for expand/collapse morphs
• spatial-zoom-navigation — Use zoom navigation transition for collection detail (iOS 18)
• spatial-transition-origin — Anchor transitions to their trigger location
• spatial-hero-shared-element — Share multiple element IDs for rich hero animations
• spatial-sheet-morph — Use matchedGeometryEffect for sheet presentations
• spatial-tab-continuity — Maintain spatial direction in tab transitions

5. Micro-interactions (HIGH)

• micro-button-press-scale — Scale buttons to 0.97 on press for tactile feedback
• micro-haptic-pairing — Pair every visual state change with haptic feedback
• micro-symbol-effect — Use symbolEffect for SF Symbol animations
• micro-toggle-bounce — Add bounce to toggle state changes
• micro-long-press-fill — Animate progressive fill for long press actions
• micro-loading-phase — Use repeating spring for organic loading states

6. Content Motion (MEDIUM-HIGH)

• content-numeric-text — Use contentTransition(.numericText) for number changes
• content-scroll-transition — Use scrollTransition for scroll-position effects
• content-visual-effect — Use visualEffect for position-aware animations
• content-symbol-replace — Animate symbol replacement with contentTransition
• content-text-renderer — Use Text Renderer for character-level animation (iOS 18)

7. Orchestration (MEDIUM)

• orch-phase-animator — Use PhaseAnimator for multi-step sequences
• orch-keyframe-animator — Use KeyframeAnimator for timeline-precise motion
• orch-stagger-children — Stagger child elements for orchestrated reveals
• orch-coordinated-entrance — Coordinate multi-element entrances with shared trigger
• orch-timeline-view — Use TimelineView for continuous repeating animations

8. Craft & Polish (MEDIUM)

• craft-reduce-motion — Respect accessibilityReduceMotion with crossfade fallback
• craft-blur-bridge — Use blur to bridge imperfect transition states
• craft-drawing-group — Use drawingGroup() for Metal-backed complex animations
• craft-geometry-group — Use geometryGroup() to isolate layout animation propagation
• craft-transaction-debug — Use Transaction to debug and override animation behavior

How to Use

Read individual reference files for detailed explanations with incorrect/correct code examples:

• Section definitions — Category structure and impact levels
• Rule template — Template for adding new rules

Reference Files