swiftui-animation-workflow

SwiftUI Animation Workflow

Purpose

Use this skill to design, implement, repair, and validate SwiftUI motion that stays state-driven, accessible, and grounded in Apple documentation. The skill owns SwiftUI animation selection, transition decisions, phase/keyframe motion, symbol-effect routing, reduce-motion checks, and preview or runtime validation handoffs.

It is not the SwiftUI app architecture workflow, not the SF Symbols selection workflow, and not the Core Animation layer workflow.

When To Use

• Use this skill when the user asks for SwiftUI animation, motion, transition, symbol-effect, or animated state-change guidance.
• Use this skill when code uses withAnimation, animation(_:value:), binding animation, transaction, transition, contentTransition, matchedGeometryEffect, navigationTransition, PhaseAnimator, KeyframeAnimator, TimelineView, Canvas, or symbolEffect.
• Use this skill when an animation is too broad, triggers unexpectedly, does not animate, ignores reduce-motion expectations, performs poorly, or mixes state ownership with side-effectful motion code.
• Use this skill when the user wants a design choice between simple state animation, transition, matched geometry, phase animation, keyframes, timeline-driven rendering, or a handoff to lower-level rendering.
• Recommend swiftui-app-architecture-workflow when the primary issue is ownership, scene structure, environment, focus, commands, or view composition rather than motion behavior.
• Recommend sf-symbols-workflow when the primary issue is choosing, coloring, validating, or customizing the symbol itself.
• Recommend xcode-build-run-workflow when the next step is preview, build, run, simulator, screenshot, or project-file validation.

Single-Path Workflow

1. Classify the motion job:
   • simple state transition
   • insertion or removal transition
   • content transition inside a stable view
   • matched geometry or navigation transition
   • phase-based animation
   • keyframe animation
   • symbol effect
   • timeline or continuously updating drawing
   • performance or accessibility repair
2. Apply the Apple docs gate:
   • read the relevant SwiftUI documentation first
   • state the documented behavior being relied on before recommending implementation
   • if Apple docs and the current code disagree, stop and surface the conflict
   • if no relevant Apple docs can be found, say that explicitly before proceeding
3. Choose the smallest motion primitive that fits the job:
   • withAnimation for one user action where all dependent changes should share a transaction
   • animation(_:value:) for a specific view subtree reacting to a specific value
   • binding animation when the control binding is the intended animation boundary
   • transaction when the task needs to override or disable animation in a subtree
   • transition for view insertion or removal
   • contentTransition for content changes inside an existing view
   • matchedGeometryEffect or navigation transition when identity and geometry continuity matter
   • PhaseAnimator for discrete phase sequences
   • KeyframeAnimator for coordinated values with explicit timing
   • TimelineView or lower-level rendering only when the motion is genuinely time-driven
4. Keep the data flow honest:
   • make animation derive from explicit state
   • avoid hidden timers, global animation state, and side effects inside frequently called animation closures
   • keep expensive work out of per-frame keyframe or timeline closures
   • keep architecture cleanup separate from motion cleanup unless the animation bug is caused by ownership confusion
5. Check accessibility and comfort:
   • verify whether reduce-motion behavior should disable, simplify, or replace motion
   • preserve meaning without relying on motion alone
   • avoid repeated decorative motion unless the user or product explicitly wants it
6. Return one recommendation path with:
   • the motion job class
   • chosen SwiftUI primitive
   • state trigger and animation boundary
   • accessibility behavior
   • documented SwiftUI behavior relied on
   • validation or handoff step