/ios-animation-design

name: ios-animation-design
description: 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.

iOS Animation Design

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.

Design Process

Gates (sequenced)

Advance only after each pass condition is met in the working artifact (chat or doc). Do not rationalize compliance without evidence.

1. **Gate — Context captured** — **Pass when** there are written answers for: what triggers the motion, its purpose, where it lives in the app, how often it runs, minimum iOS version, and primary input methods (or explicit **N/A** where not applicable). **Pass when** you have stated whether system-provided motion already covers this or which gap custom animation fills. 2. **Gate — Options differ meaningfully** — **Pass when** there are 2–3 approaches and each differs in **at least two** of: named API/technique, motion character, complexity band, or iOS floor — not minor timing tweaks of the same idea. 3. **Gate — Spec is implementation-ready** — **Pass when** the compiled spec includes concrete entries for **Trigger**, **Interruption** (cancel/reverse/queue), **Reduce Motion** fallback, **Haptics** (or explicit none with rationale), and **Recommended API**.

Step 1: Understand the Animation Context

Before proposing options, gather context about what needs to animate and why:

• **What triggers it?** User action (tap, swipe, drag), state change (data loaded, error), or lifecycle event (appear, disappear)?
• **What's the purpose?** Feedback, spatial orientation, content transition, delight, or status communication?
• **Where in the app?** Navigation flow, in-screen state change, overlay/modal, or background ambient?
• **How frequent?** Once per session (onboarding), every interaction (tab switch), or continuous (progress indicator)? Apple's HIG warns: "In apps, generally avoid adding motion to UI interactions that occur frequently. The system already provides subtle animations for interactions with standard interface elements."
• **Deployment target?** Which iOS version floor determines available APIs.
• **Input methods?** Touch, trackpad, keyboard, VoiceOver? iOS 26's Liquid Glass adapts motion intensity based on input — direct touch gets more emphasis, indirect input is more subdued. Custom animations should follow the same principle.

Step 2: Present 2-3 Animation Approaches

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:

• API availability relative to the deployment target
• Complexity budget — simpler is better unless the animation is a signature moment
• Whether the system already handles it — prefer system-provided motion over custom implementations
• Consistency with existing app motion language
• Cancellability — can users interrupt or skip it? ("Don't make people wait for an animation to complete before they can do anything" — Apple HIG)
• Accessibility (can it gracefully degrade with Reduce Motion?)
• Multimodal feedback — animation alone shouldn't be the only signal. "Supplement visual feedback by also using alternatives like haptics and audio" (Apple HIG)

Step 3: Compile the Animation Spec

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 Format

# 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, lon