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/swiftui-animation-patterns.md
View on GitHub# SwiftUI Animation Patterns
## withAnimation Scope Issues
`withAnimation` should wrap only the state mutation that drives the animation, not unrelated logic.
```swift
// BAD — animation wraps network call and unrelated state
withAnimation {
Task { await viewModel.fetchData() }
selectedTab = .home
showBanner = false
}
// GOOD — only the visual state change is animated
Task { await viewModel.fetchData() }
withAnimation(.snappy) {
selectedTab = .home
}
showBanner = false
```
## Deprecated .animation() Without Value
The parameterless `.animation(_:)` modifier is deprecated. It animates every state change in the view, causing unexpected animations on unrelated properties.
```swift
// BAD — deprecated, animates everything
Text(name)
.animation(.spring())
// GOOD — explicit value binding
Text(name)
.animation(.spring(), value: isExpanded)
```
## Spring Parameter Anti-Patterns
| Pattern | Problem |
|---------|---------|
| `.spring(mass:stiffness:damping:)` in SwiftUI | Old API — use `duration`/`bounce` instead |
| `duration: 0` on a spring | Undefined behavior — use `.none` for instant |
| `bounce: 1.0` or higher | Extremely bouncy, likely unintentional — values above 0.5 are unusual |
| `.easeInOut(duration: 0.25)` for interactive feedback | Springs feel more natural for user interactions |
## PhaseAnimator Issues
### Infinite Loop Without Trigger
`PhaseAnimator` without a `trigger` parameter loops continuously. This is intentional for ambient animations but a bug if used for one-shot effects.
```swift
// This loops forever — intentional?
.phaseAnimator([false, true]) { content, phase in
content.opacity(phase ? 1 : 0.5)
}
// One-shot: add trigger
.phaseAnimator([false, true], trigger: tapCount) { content, phase in
content.opacity(phase ? 1 : 0.5)
}
```
### Single Phase
A `PhaseAnimator` with only one phase does nothing.
```swift
// BUG — needs at least 2 phases
.phaseAnimator([Phase.idle]) { /* never transitions */ }
```
## KeyframeAnimator Issues
### Mismatched Track Properties
Keyframe tracks must reference properties that exist on the `initialValue` type.
```swift
// BUG — if AnimationValues doesn't have .blur, this crashes
KeyframeTrack(\.blur) { ... }
```
### Missing Duration on Keyframes
Every keyframe needs a `duration`. Omitting it defaults to 0, making the keyframe instant.
```swift
// BAD — instant jump, probably unintentional
SpringKeyframe(1.5)
// GOOD — explicit duration
SpringKeyframe(1.5, duration: 0.3)
```
## Content Transition Misuse
`.contentTransition` is for content changes within a view, not view insertion/removal.
```swift
// BAD — contentTransition on a conditional view
if isVisible {
Text("Hello")
.contentTransition(.opacity) // Wrong — use .transition()
}
// GOOD — for content that changes in place
Text(count, format: .number)
.contentTransition(.numericText())
```
## Symbol Effect on Non-SF-Symbols
`.symbolEffect` only works with SF Symbols (system images). Applied to custom images, it silently does nothing.
```swift
// No effect — custom image, not SF Symbol
Image("custom-icon")
.symbolEffect(.bounce, value: count)
// Works — SF Symbol
Image(systemName: "bell.badge")
.symbolEffect(.bounce, value: count)
```
## Animation Identity vs. Transition
Animating the `.id()` modifier destroys and recreates the view. This is almost never what you want for smooth animation.
```swift
// BAD — destroys view identity, no smooth animation
Text(name)
.id(currentUser.id) // View is destroyed and recreated on change
.animation(.spring(), value: currentUser.id)
// GOOD — transition for view swap
Text(name)
.transition(.opacity)
.id(currentUser.id)
// GOOD — matchedGeometryEffect for position/size animation
Text(name)
.matchedGeometryEffect(id: "title", in: namespace)
```
## Critical Anti-Patterns
| Pattern | Issue |
|---------|-------|
| `.animation()` without `value:` | Deprecated, animates all state changes unpredictably |
| `withAnimation` wrapping `Task { }` | Async work doesn't need animation wrapping |
| `PhaseAnimator` with 1 phase | Does nothing — needs ≥ 2 phases to transition |
| `.symbolEffect` on custom images | Silently fails — only works with SF Symbols |
| Animating `.id()` modifier changes | Destroys view — use `transition` or `matchedGeometryEffect` |
| `spring(bounce: > 0.5)` | Excessively bouncy — verify this is intentional |
## Review Questions
1. Is `.animation()` always paired with a `value:` parameter?
2. Does `withAnimation` scope include only the state mutation, not side effects?
3. Are `PhaseAnimator` phase counts ≥ 2 and triggered appropriately (continuous vs. one-shot)?
4. Are `KeyframeAnimator` track properties matching the `initialValue` struct?
5. Is `.symbolEffect` only applied to SF Symbols?
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 |