existential-birds/beagle / plugins/beagle-ios/skills/ios-animation-code-review
ios-animation-code-review
VerifiedReviews 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| references/accessibility.md | markdown | 6.5 KB |
| references/performance.md | markdown | 6.0 KB |
| references/swiftui-animation-patterns.md | markdown | 4.8 KB |
| references/transitions.md | markdown | 6.6 KB |
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?
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |