swiftui-motionlisted

> **Version-sensitive.** Every API name, SDK gate and browser-support claim below was > verified on **2026-09-08** against primary sources. What against, and when, is in > `_jutsu/VERSIONS.md`. If that date is old, re-verify before acting on a version number. # SwiftUI Motion > SwiftUI animation core. Loaded for any SwiftUI project (iOS, macOS, multi-target Apple). > Concise rules here. Deep-dive in `references/`. > Pair with `../motion-principles/SKILL.md` (foundation) and `../mobile-principles/SKILL.md` (touch UX). --- ## Animation API decision tree | Need | API | |---|---| | Single value over time | `withAnimation { } + @State` or `.animation(_, value:)` | | Multiple coordinated states | `PhaseAnimator(phases)` (iOS 17+) | | Time-based keyframes | `KeyframeAnimator(initialValue:repeating:content:)` (iOS 17+) | | Custom property animations | `@Animatable` macro (needs Xcode 26 / SwiftUI 2025 SDK to compile; **runtime availability iOS 13.0+ / macOS 10.15+ / watchOS 6.0+**) or the `Animatable` protocol by hand (iOS 13+) | | Shared element transitions | `matchedGeometryEffect(id:in:)` | | Gesture-driven | `DragGesture` / `MagnifyGesture` + `.offset` / `.scaleEffect` | | Loop forever | `.animation(.linear.repeatForever(autoreverses: true), value: ...)` or `.phaseAnimator` | **Rule:** start with `withAnimation`. Reach for `PhaseAnimator` only when you have 3+ ordered states. Reach for `KeyframeAnimator` only when you need parallel time-based tracks. --- ## Springs (the o