abdullah4ai/animations

Animations

Enforce safe, performant animations that never escape their parent bounds.

CONTAINMENT (CRITICAL): Animated content inside a container (card, row, sheet, etc.) MUST NOT overflow its parent. Apply containment modifiers on the PARENT that clips:

// CORRECT — compositingGroup flattens, clipped constrains
CardContainer {
    AnimatedContent()
        .transition(.scale.combined(with: .opacity))
}
.compositingGroup()
.clipped()

// WRONG — animated child overflows parent during transition
CardContainer {
    AnimatedContent()
        .transition(.move(edge: .bottom))
}
// No containment — content renders outside CardContainer

WHY .compositingGroup().clipped():

• .compositingGroup() flattens child layers into one compositing pass (no Metal overhead like .drawingGroup())
• .clipped() then clips that single composited layer to the parent frame
• Together they guarantee zero visual overflow during any animation phase
• Do NOT use .drawingGroup() for this — it rasterizes via Metal, wastes memory, and redraws the entire group on any change
• Do NOT rely on .scaleEffect(1) hack — it is fragile and undocumented behavior

WHEN TO APPLY CONTAINMENT:

• Any view with .transition() inside a sized container (cards, rows, sheets, popovers)
• Spring/bouncy animations on child views that may overshoot parent bounds
• Phase animations or keyframe animations that scale or offset children
• ScrollView items with animated insertion/removal

WHEN CONTAINMENT IS NOT NEEDED:

• Full-screen views with no parent clipping boundary
• Opacity-only animations (no spatial overflow possible)
• Navigation transitions handled by the system

MODIFIER ORDER:

// CORRECT — animation AFTER layout, containment on parent
VStack {
    content
        .offset(y: animating ? -20 : 0)
        .opacity(animating ? 0 : 1)
        .animation(.spring(duration: 0.4), value: animating)
}
.compositingGroup()
.clipped()

// WRONG — animation before layout modifiers
content
    .animation(.spring, value: state)
    .padding()
    .frame(maxWidth: .infinity)

PREFER GPU TRANSFORMS:

• Use .scaleEffect, .offset, .rotationEffect, .opacity — GPU-accelerated, no layout pass
• Avoid animating .frame, .padding, .font — triggers full layout recalculation

// GOOD — GPU transform, no layout hit
Text("Hello")
    .scaleEffect(isPressed ? 0.95 : 1.0)
    .animation(.spring(duration: 0.2), value: isPressed)

// BAD — layout-driven animation
Text("Hello")
    .padding(isPressed ? 10 : 16)
    .animation(.spring, value: isPressed)

TIMING CURVES:

• .spring(duration: 0.3) — default for most UI (buttons, toggles, cards)
• .spring(duration: 0.4, bounce: 0.3) — playful emphasis (success states, celebrations)
• .easeInOut(duration: 0.25) — subtle transitions (opacity, color changes)
• .bouncy — ONLY for intentional delight moments, never on frequent actions
• Keep durations under 0.5s for responsive feel

TRANSITIONS:

• Place withAnimation or .animation OUTSIDE the conditional — not inside the branch

// CORRECT
withAnimation(.spring(duration: 0.3)) {
    showDetail.toggle()
}
// In body:
if showDetail {
    DetailView()
        .transition(.opacity.combined(with: .move(edge: .bottom)))
}

// WRONG — animation inside the conditional
if showDetail {
    DetailView()
        .animation(.spring, value: showDetail) // too late
}

ANIMATION SCOPE:

• Bind .animation to a specific value — NEVER use .animation(.spring) without value parameter
• Use withAnimation for user-triggered state changes
• Use .animation(_:value:) for derived/computed state changes

// CORRECT — scoped to specific value
.animation(.easeInOut(duration: 0.2), value: isSelected)

// WRONG — unscoped, animates everything
.animation(.easeInOut)

LIST AND SCROLL ANIMATIONS:

• Use .animation on the List/ForEach container, not individual rows
• Containment is especially important for row insertion/removal animations

List {
    ForEach(items) { item in
        ItemRow(item: item)
    }
}
.animation(.spring(duration: 0.3), value: items.count)

PHASE AND KEYFRAME (iOS 17+):

• PhaseAnimator: use for looping multi-step sequences (loading indicators, attention pulses)
• KeyframeAnimator: use for precise multi-property choreography
• Both MUST have containment if inside a bounded parent

// Phase animation with containment
PhaseAnimator([false, true]) { phase in
    Icon()
        .scaleEffect(phase ? 1.1 : 1.0)
        .opacity(phase ? 1.0 : 0.7)
}
.compositingGroup()
.clipped()