Skip to content

existential-birds/beagle / plugins/beagle-ios/skills/ios-animation-code-review

ios-animation-code-review

Verified

Reviews iOS animation code for correctness, performance, accessibility, and Apple API best practices. Use when reviewing .swift files containing animation code — withAnimation, .animation(), PhaseAnimator, KeyframeAnimator, matchedGeometryEffect, navigationTransition, CABasicAnimation, CASpringAnimation, UIViewPropertyAnimator, UIDynamicAnimator, symbolEffect, scrollTransition, contentTransition, or custom Transition conformances.

references/transitions.md

View on GitHub
# Transition Review Patterns

## matchedGeometryEffect Issues

### Duplicate IDs in Same Namespace

Only one view with a given ID should be in the view hierarchy at a time. Two visible views sharing an ID causes undefined geometry matching.

```swift
// BUG — both views visible with same ID
ZStack {
    SourceView()
        .matchedGeometryEffect(id: "card", in: namespace)
        .opacity(isExpanded ? 0 : 1)  // Opacity 0 still counts as "in hierarchy"
    DestinationView()
        .matchedGeometryEffect(id: "card", in: namespace)
        .opacity(isExpanded ? 1 : 0)
}

// GOOD — conditional, only one in hierarchy
if isExpanded {
    DestinationView()
        .matchedGeometryEffect(id: "card", in: namespace)
} else {
    SourceView()
        .matchedGeometryEffect(id: "card", in: namespace)
}
```

### Unstable IDs

The matched ID must be stable across the transition. Using array indices or computed values that change during the animation breaks the match.

```swift
// BAD — index changes when array mutates
ForEach(Array(items.enumerated()), id: \.offset) { index, item in
    ItemView(item: item)
        .matchedGeometryEffect(id: index, in: namespace)  // Index shifts on delete
}

// GOOD — stable model ID
ForEach(items) { item in
    ItemView(item: item)
        .matchedGeometryEffect(id: item.id, in: namespace)
}
```

### Missing isSource

When matching position and size separately (rare but valid), one side must be `isSource: true` and the other `isSource: false`. When matching both together (common case), both default to `isSource: true` which works correctly.

### Namespace Scope

`@Namespace` must be declared in the common ancestor view that contains both the source and destination. Passing namespaces between unrelated view hierarchies doesn't work.

## Custom Transition Protocol

### TransitionPhase Misunderstanding

`TransitionPhase` has three cases. `.willAppear` is the "before" state for insertion, `.didDisappear` is the "after" state for removal, and `.identity` is the normal presented state.

```swift
// BUG — this makes the view invisible in its identity state
struct BrokenTransition: Transition {
    func body(content: Content, phase: TransitionPhase) -> some View {
        content
            .opacity(phase == .willAppear ? 0 : 1)
            // Removal: .didDisappear gets opacity 1, then view disappears without fade
    }
}

// GOOD — both insertion and removal handled
struct CorrectTransition: Transition {
    func body(content: Content, phase: TransitionPhase) -> some View {
        content
            .opacity(phase.isIdentity ? 1 : 0)  // 0 for both willAppear and didDisappear
            .scaleEffect(phase.isIdentity ? 1 : 0.8)
    }
}
```

### Asymmetric Behavior

If insertion and removal should look different, use `.asymmetric()` or check the specific phase.

```swift
struct AsymmetricSlide: Transition {
    func body(content: Content, phase: TransitionPhase) -> some View {
        content
            .offset(
                x: phase == .willAppear ? 100 :    // Enter from right
                   phase == .didDisappear ? -100 :  // Exit to left
                   0                                 // Identity
            )
            .opacity(phase.isIdentity ? 1 : 0)
    }
}
```

## Zoom Navigation Transition (iOS 18+)

### Missing matchedTransitionSource

`.navigationTransition(.zoom(sourceID:in:))` on the destination requires `.matchedTransitionSource(id:in:)` on the source. Without it, the zoom has no origin point and falls back to a standard push.

```swift
// BUG — missing source
NavigationLink {
    DetailView()
        .navigationTransition(.zoom(sourceID: item.id, in: namespace))
} label: {
    ItemCell()
    // No .matchedTransitionSource — zoom won't work
}

// GOOD
NavigationLink {
    DetailView()
        .navigationTransition(.zoom(sourceID: item.id, in: namespace))
} label: {
    ItemCell()
        .matchedTransitionSource(id: item.id, in: namespace)
}
```

### ID Mismatch

The `sourceID` in `.navigationTransition(.zoom)` must exactly match the `id` in `.matchedTransitionSource`. Type must also match (both String, both Int, etc.).

### Outside NavigationStack

Zoom transitions require `NavigationStack`. They don't work with the deprecated `NavigationView` or with custom navigation implementations.

## View Transition Timing

### Missing Animation Wrapper

Conditional view changes need `withAnimation` or `.animation(_:value:)` to animate transitions.

```swift
// BUG — no animation, views snap in/out
if showDetail {
    DetailView()
        .transition(.slide)  // Transition defined but never animated
}

// GOOD — wrapped in animation
Button("Show") {
    withAnimation(.spring()) {
        showDetail = true
    }
}
if showDetail {
    DetailView()
        .transition(.slide)
}
```

### Transition on Wrong View

`.transition()` must be on the view being inserted/removed, not the parent.

```swift
// BAD — transition on container, not on the conditional view
VStack {
    if showBanner {
        BannerView()
    }
}
.transition(.slide)  // Does nothing — VStack is always present

// GOOD — transition on the conditional view
VStack {
    if showBanner {
        BannerView()
            .transition(.slide)
    }
}
```

## NavigationStack Path Animation

Programmatic navigation changes should be wrapped in `withAnimation` for smooth transitions.

```swift
// No animation — instant view swap
path.append(destination)

// Animated
withAnimation(.smooth) {
    path.append(destination)
}
```

## Critical Anti-Patterns

| Pattern | Issue |
|---------|-------|
| Two views with same matchedGeometryEffect ID visible simultaneously | Undefined geometry matching |
| `matchedGeometryEffect` with array index as ID | ID shifts when array mutates |
| `.transition()` on a view that's always in the hierarchy | No effect — transitions only fire on insertion/removal |
| `.navigationTransition(.zoom)` without `.matchedTransitionSource` | Falls back to standard push, no zoom |
| Missing `withAnimation` around conditional view state change | Transition defined but never animated |
| Custom Transition that only handles `.willAppear` | Removal has no animation |

## Review Questions

1. For `matchedGeometryEffect` — is only one view with that ID in the hierarchy at a time?
2. Does the custom `Transition` handle both `.willAppear` and `.didDisappear` phases?
3. For zoom navigation — does every `.navigationTransition(.zoom)` have a matching `.matchedTransitionSource` with the same ID?
4. Is the view state change that triggers the transition wrapped in `withAnimation`?
5. Is `.transition()` placed on the conditional view, not its always-present parent?
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall