Swiftui Animations

Spring presets (prefer over .default):

• .bouncy() — playful, high-energy (achievements, celebrations)
• .smooth() — premium, no bounce (financial data, detail transitions)
• .snappy — responsive selection feedback (filter chips, toggles)
• .interpolatingSpring(stiffness:damping:) — full manual control

Critical Gotchas

1. Implicit animation transition bug (Xcode 11.2+)

Transitions silently fail if triggered by implicit animations. Always wrap state changes in withAnimation {} OR attach animation to transition directly:

// ✅ Safe
.transition(.scale.animation(.bouncy()))

// ❌ Breaks silently
someView.animation(.bouncy()) // implicit — transition may not fire

2. NavigationView / NavigationStack clipping

Toast alerts and overlay sheets placed directly over a NavigationStack may disappear instantly without animating. Always present overlays from the root ZStack, not from inside a navigation destination.

3. iOS 18 interrupted navigation transitions

Zoom transitions are interactive. If a user starts a pop while a push is still animating, the system force-completes the push immediately. Do not gate any logic on "transition in progress." Clean up all transition state in onAppear/onDisappear.

4. Dynamic type runaway

Complex grids and metric cards break at accessibility font sizes. Apply .minimumScaleFactor(0.7) on tight numeric displays and cap dynamic type with .dynamicTypeSize(...<= .xxxLarge) on widget grids.

5. Services must not import SwiftUI

Use a delegate protocol or @Published property on the service. The view wraps mutations in withAnimation. Never put animation logic in a Service layer.

Open-Source Reference Library

Cloned at: C:\Users\wowth\Documents\projects\open-swiftui-animations

HIGH priority — steal these patterns

MEDIUM — reference for specific problems

iFlip-Specific Conventions

Existing animation infrastructure (read these before writing new animations)

• DesignSystem/Transitions.swift — .pushTransition / .popTransition defined but currently unused in NavigationStack destinations. Apply these.
• DesignSystem/DesignSystem.swift — Colors.forRarity(_:) maps AchievementRarity to token color. Always use this, never hardcode hex.
• Services/GamificationManager.swift — uses GamificationVisualDelegate protocol to keep SwiftUI out of Services.
• Services/HapticManager.swift — triggerStandardHaptics(for rarity:) exists. Use it.

Rarity → animation intensity

Animation constants (no hardcoded values)

There are currently no centralized timing tokens. Until they exist, use these values consistently:

• Fast: response: 0.3, dampingFraction: 0.7
• Standard: response: 0.4, dampingFraction: 0.6
• Celebration: .bouncy(duration: 0.5, extraBounce: 0.1)
• Slow/premium: response: 0.6, dampingFraction: 0.85

Haptic Pairing

Pair every meaningful interaction with haptics. Use .sensoryFeedback() modifier (iOS 17+) over manual UIImpactFeedbackGenerator where possible:

.sensoryFeedback(.impact(flexibility: .soft), trigger: selectedFilter)
.sensoryFeedback(.success, trigger: itemSold)
.sensoryFeedback(.warning, trigger: deleteConfirmed)

Missing haptics in iFlip (add these): filter chip taps, swipe action completions, list item taps, achievement badge taps, status changes.

List Stagger Pattern

ForEach(Array(items.enumerated()), id: \.element.id) { index, item in
    ItemRow(item: item)
        .transition(.scale(scale: 0.95).combined(with: .opacity))
        .animation(
            .spring(response: 0.5, dampingFraction: 0.8)
                .delay(Double(index) * 0.04),
            value: items.count
        )
}

Cap delay at ~20 items (min(index, 20) * 0.04) to avoid long waits on large lists.

Reduce Motion Template

@Environment(\.accessibilityReduceMotion) var reduceMotion

var body: some View {
    content
        .animation(reduceMotion ? .none : .bouncy(), value: isVisible)
}

For Canvas-based particles: skip the TimelineView entirely and show a static icon + opacity fade.

Advanced Techniques

Shape-clipping cross-fade: Use an animated shape to clip incoming/outgoing views for custom cross-effects instead of plain opacity. Apply to photo preview transitions and item detail reveals.

Custom parameterized transition (stripe blinds):

extension AnyTransition {
    static func stripes(count: Int, horizontal: Bool) -> AnyTransition {
        .modifier(active: StripesModifier(count: count, horizontal: horizontal, progress: 0),
                  identity: StripesModifier(count: count, horizontal: horizontal, progress: 1))
    }
}
// StripesModifier conforms to Animatable + ViewModifier, clips view into N animated stripes

iOS 18 interactive zoom (mid-transition drag):

// Source view
.matchedTransitionSource(id: item.id, in: namespace)
// Destination
.navigationTransition(.zoom(sourceID: item.id, in: namespace))
// User can grab and drag mid-transition — do NOT gate logic on transition state

GeometryEffect custom modal: Extend AnyTransition + GeometryEffect for fully custom modal present/dismiss (e.g., item detail expanding from list row).

Velocity-preserving fling:

.gesture(DragGesture()
    .onChanged { value in
        offset = value.translation  // .interactiveSpring updates target continuously
    }
    .onEnded { _ in
        withAnimation(.spring()) { offset = finalPosition }  // preserves velocity
    }
)

Animated path drawing: trim(from: 0, to: progress) on a Path, animate progress 0→1. Use for goal completion checkmark stroke animation.

Per-character 3D flip:

ForEach(Array(text.enumerated()), id: \.offset) { index, char in
    Text(String(char))
        .rotation3DEffect(isRevealed ? .zero : .degrees(90), axis: (0, 1, 0))
        .animation(.bouncy().delay(Double(index) * 0.05), value: isRevealed)
}

AI loading state with phaseAnimator: Instead of a spinner, cycle through engaging phases (scanning → thinking → analyzing → almost done) with visual transitions between each. Keeps user engaged during enrichment pipeline.

Anchored rotation: Specify .rotationEffect(angle, anchor: .bottomLeading) to rotate around a custom point rather than center. Good for "flip card" or "door open" effects on item cards.

Common Mistakes