Design and plan iOS animations with structured specs covering transitions, micro-interactions, gesture-driven motion, and loading states. Use when the user asks to plan, design, or spec out animations for an iOS app — including screen transitions, navigation animations, interactive gestures, onboarding flows, or any motion design work. Also use when the user wants animation recommendations or wants to decide between animation approaches before writing code.
Plan animations that feel intentional, not decorative. Apple's HIG is clear: "Don't add motion for the sake of adding motion. Gratuitous or excessive animation can distract people and may make them feel disconnected or physically uncomfortable." Every animation must serve a purpose — guide attention, communicate state changes, reinforce spatial relationships, or provide feedback.
Before adding any custom animation, ask: does the system already handle this? Many system components include motion automatically — Liquid Glass (iOS 26) responds to touch with greater emphasis and produces more subdued effects for trackpad interaction. Standard controls, navigation transitions, and sheets already animate. Custom motion should fill gaps the system doesn't cover, not replace what it already does well.
Before proposing options, gather context about what needs to animate and why:
For each animation need, present 2-3 distinct approaches. Each option should feel meaningfully different — not minor variations of the same idea. Structure each option as:
### Option [N]: [Name]
**Approach**: [1-2 sentences describing the motion design]
**Technique**: [Which Apple API — SwiftUI animation, KeyframeAnimator, matchedGeometryEffect, etc.]
**Character**: [How it feels — snappy, playful, elegant, subtle, dramatic]
**Complexity**: [Low / Medium / High — implementation and maintenance cost]
**iOS floor**: [Minimum iOS version required]
Then provide a Recommendation with rationale tied to the gathered context. The recommendation should consider:
Once the user selects an approach (or confirms the recommendation), produce a structured spec. This spec is the contract between design and implementation — it should contain everything needed to write the code without ambiguity.
# Animation Spec: [Name]
## Overview
[1-2 sentences: what this animation does and why it exists]
## Trigger
- **Event**: [What initiates the animation — tap, state change, appear, gesture, etc.]
- **Direction**: [Forward / Reverse / Bidirectional]
## Motion Design
### Properties
| Property | From | To | Curve | Duration |
|----------|------|----|-------|----------|
| opacity | 0 | 1 | .easeOut | 0.25s |
| scale | 0.8 | 1.0 | .spring(duration: 0.5, bounce: 0.3) | — |
| offset.y | 20 | 0 | .spring(duration: 0.5, bounce: 0.3) | — |
### Timing
- **Total duration**: [end-to-end time]
- **Stagger**: [if multiple elements, delay between each]
- **Interruption**: [What happens if triggered again mid-animation — cancel, reverse, queue]
### Gesture Binding (if interactive)
- **Gesture type**: [drag, long press, rotation, magnification]
- **Progress mapping**: [How gesture progress maps to animation progress]
- **Threshold**: [When the animation commits vs. cancels]
- **Velocity handling**: [How release velocity affects completion]
## Accessibility & Multimodal Feedback
- **Reduce Motion**: [What happens — crossfade, instant, simplified version]
- **VoiceOver**: [Any announcement needed for the state change]
- **Haptics**: [Which sensoryFeedback type pairs with this animation — .impact, .selection, .success, etc.]
- **Audio**: [Optional sound cue if the state change is important enough]
- **Dynamic Type**: [Does layout shift affect the animation?]
## Implementation Notes
- **Recommended API**: [SwiftUI withAnimation, KeyframeAnimator, PhaseAnimator, matchedGeometryEffect, UIViewPropertyAnimator, etc.]
- **State model**: [What @State/@Binding drives this animation]
- **Extractable component**: [Yes/No — should this be a reusable ViewModifier or View?]
When designing, think in terms of these categories. Each has different expectations for timing, easing, and purpose.
Screen-to-screen movement. Users expect spatial consistency — where did I come from, where am I going? These should feel fast and confident.
matchedGeometryEffect, navigationTransition(.zoom))Transition protocol)Timing: 0.3–0.5s. Easing: spring-based (.snappy or .smooth). Interruption: must handle back-gesture gracefully.
Small, immediate feedback for user actions. Apple's HIG emphasizes brevity: "When animated feedback is brief and precise, it tends to feel lightweight and unobtrusive, and it can often convey information more effectively than prominent animation." These should be near-instant and never block interaction. For frequent interactions, strongly consider whether the system's built-in animation is sufficient before adding custom motion.
Timing: 0.1–0.3s. Easing: .snappy or .spring(duration: 0.2, bounce: 0.4). Always pair with sensoryFeedback — haptics reinforce the visual feedback and communicate to users who can't see the animation.
When data changes within a view — numbers updating, content swapping, list reordering.
.contentTransition(.numericText))Timing: 0.2–0.35s. Easing: .smooth or .easeInOut. Use animation(_:value:) tied to the changing data.
Interactive animations where the user directly controls progress. These need to feel physically connected to the finger — no lag, no disconnection.
scrollTransition)Spring-based completion is essential. Track velocity on release. Use UIViewPropertyAnimator for UIKit or GestureState + spring for SwiftUI.
Communicate waiting and progress. Should feel alive without being distracting.
.symbolEffect(.pulse))PhaseAnimator)Keep looping animations lightweight — they run continuously and must not drain battery or cause hitches.
Background motion that establishes mood. Use sparingly — these are the easiest to overdo.
MeshGradient with timer-driven point shifts)Always disable or simplify with Reduce Motion. These are the first to cut for performance.
duration + bounce parameters, not bezier curves, unless you have a specific reason..sensoryFeedback) and audio where appropriate. Animation alone shouldn't carry critical state changes.