@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swiftui-animation/SKILL.md

@@ -1,309 +1,266 @@
 ---
 name: swiftui-animation
-description: "Implement, review, or improve SwiftUI animations and transitions. Use when adding explicit animations with withAnimation, configuring implicit animations with .animation(_:body:) or .animation(_:value:), configuring spring animations (.smooth, .snappy, .bouncy), building phase or keyframe animations with PhaseAnimator/KeyframeAnimator, creating hero transitions with matchedGeometryEffect or matchedTransitionSource, adding SF Symbol effects (bounce, pulse, variableColor, breathe, rotate, wiggle), implementing custom Transition or CustomAnimation types, or ensuring animations respect accessibilityReduceMotion."
+description: "SwiftUI motion: withAnimation, scoped implicit .animation(_:body:) and .animation(_:value:), timing curves and springs (.smooth, .snappy, .bouncy, Spring), PhaseAnimator, KeyframeAnimator, @Animatable, matchedGeometryEffect and matchedTransitionSource zoom transitions, insertion and content transitions, SF Symbol effects (pulse, bounce, wiggle, rotate, breathe, variableColor), custom Transition and CustomAnimation, performance, Core Animation bridging. Use when implementing, reviewing or improving SwiftUI animations and transitions, or making them respect accessibilityReduceMotion."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # SwiftUI Animation (iOS 26+)
 
-Review, write, and fix SwiftUI animations. Apply modern animation APIs with
-correct timing, transitions, and accessibility handling using Swift 6.3 patterns.
-
-## Contents
-
-- [Triage Workflow](#triage-workflow)
-- [withAnimation (Explicit Animation)](#withanimation-explicit-animation)
-- [Implicit Animation](#implicit-animation)
-- [Spring Type (iOS 17+)](#spring-type-ios-17)
-- [PhaseAnimator (iOS 17+)](#phaseanimator-ios-17)
-- [KeyframeAnimator (iOS 17+)](#keyframeanimator-ios-17)
-- [`@Animatable Macro`](#animatable-macro)
-- [matchedGeometryEffect (iOS 14+)](#matchedgeometryeffect-ios-14)
-- [Navigation Zoom Transition (iOS 18+)](#navigation-zoom-transition-ios-18)
-- [Transitions (iOS 17+)](#transitions-ios-17)
-- [ContentTransition (iOS 16+)](#contenttransition-ios-16)
-- [Symbol Effects (iOS 17+)](#symbol-effects-ios-17)
-- [Symbol Rendering Modes](#symbol-rendering-modes)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Triage Workflow
-
-### Step 1: Identify the animation category
-
-| Category | API | When to use |
-|---|---|---|
-| State-driven | `withAnimation`, `.animation(_:body:)`, `.animation(_:value:)` | Explicit state changes, selective modifier animation, or simple value-bound changes |
-| Multi-phase | `PhaseAnimator` | Sequenced multi-step animations |
-| Keyframe | `KeyframeAnimator` | Complex multi-property choreography |
-| Shared element | `matchedGeometryEffect` | Layout-driven hero transitions |
-| Navigation | `matchedTransitionSource` + `.navigationTransition(.zoom)` | NavigationStack push/pop zoom |
-| View lifecycle | `.transition()` | Insertion and removal |
-| Text content | `.contentTransition()` | In-place text/number changes |
-| Symbol | `.symbolEffect()` | SF Symbol animations |
-| Custom | `CustomAnimation` protocol | Novel timing curves |
-
-### Step 2: Choose the animation curve
+How to get timing, transitions and accessibility right with the current
+animation APIs. Examples assume iOS 26 and Swift 6.3; sections name the
+release an API first shipped in.
 
-```swift
-// Timing curves
-.linear                              // constant speed
-.easeIn(duration: 0.3)              // slow start
-.easeOut(duration: 0.3)             // slow end
-.easeInOut(duration: 0.3)           // slow start and end
-
-// Spring presets (preferred for natural motion)
-.smooth                              // no bounce, fluid
-.smooth(duration: 0.5, extraBounce: 0.0)
-.snappy                              // small bounce, responsive
-.snappy(duration: 0.4, extraBounce: 0.1)
-.bouncy                              // visible bounce, playful
-.bouncy(duration: 0.5, extraBounce: 0.2)
-
-// Custom spring
-.spring(duration: 0.5, bounce: 0.3, blendDuration: 0.0)
-.spring(Spring(duration: 0.6, bounce: 0.2), blendDuration: 0.0)
-.interactiveSpring(response: 0.15, dampingFraction: 0.86)
-```
+## Triage
 
-### Step 3: Apply and verify
+### 1. Pick the tool for the job
 
-- Confirm animation triggers on the correct state change.
-- Test with Accessibility > Reduce Motion enabled.
-- Verify no expensive work runs inside animation content closures.
+| What moves | API |
+|---|---|
+| A state change you trigger, a few modifiers, or one value | `withAnimation`; `.animation(_:value:)`; `.animation(_:body:)` |
+| A sequence of distinct steps | `PhaseAnimator` |
+| Several properties on independent timelines | `KeyframeAnimator` |
+| A shared element between two layouts | `matchedGeometryEffect` |
+| A push or pop in `NavigationStack` that grows from a tile | `matchedTransitionSource` + `.navigationTransition(.zoom)` |
+| A view being inserted or removed | `.transition()` |
+| Text, numbers or a symbol changing in place | `.contentTransition()` |
+| An SF Symbol reacting | `.symbolEffect()` |
+| A timing curve no built-in covers | `CustomAnimation` |
 
-## withAnimation (Explicit Animation)
+### 2. Pick the curve
+
+Timing curves suit mechanical motion:
 
 ```swift
-withAnimation(.spring) { isExpanded.toggle() }
+.linear                     // constant speed
+.easeIn(duration: 0.3)      // starts slow
+.easeOut(duration: 0.3)     // ends slow
+.easeInOut(duration: 0.3)   // slow at both ends
+```
 
-// With completion (iOS 17+)
-withAnimation(.smooth(duration: 0.35), completionCriteria: .logicallyComplete) {
-    isExpanded = true
-} completion: { loadContent() }
+Springs feel physical and are the better default for anything a person
+touches or watches:
+
+```swift
+.smooth                                   // settles with no overshoot
+.smooth(duration: 0.6)
+.snappy                                   // quick, a hint of bounce
+.snappy(duration: 0.3, extraBounce: 0.05)
+.bouncy                                   // noticeable, playful overshoot
+.bouncy(duration: 0.6, extraBounce: 0.1)
+
+.spring(duration: 0.45, bounce: 0.25, blendDuration: 0.1)
+.spring(Spring(duration: 0.7, bounce: 0.15), blendDuration: 0.2)
+.interactiveSpring(response: 0.2, dampingFraction: 0.8)
 ```
 
-## Implicit Animation
+### 3. Apply, then check
+
+- It fires on the state change you meant, and only that one.
+- It still makes sense with Settings > Accessibility > Motion > Reduce Motion
+  on.
+- Closures that run per frame do no expensive work.
 
-Prefer `.animation(_:body:)` when only specific modifiers should animate.
-Use `.animation(_:value:)` for simple value-bound changes that can animate the
-view's animatable modifiers together.
+## Explicit animation
+
+Wrap the mutation, not the view:
 
 ```swift
-Badge()
-    .foregroundStyle(isActive ? .green : .secondary)
-    .animation(.snappy) { content in
-        content
-            .scaleEffect(isActive ? 1.15 : 1.0)
-            .opacity(isActive ? 1.0 : 0.7)
-    }
+Button("Details") {
+    withAnimation(.spring) { showsDetails.toggle() }
+}
 ```
 
+From iOS 17, a completion runs when the animation is done:
+
 ```swift
-Circle()
-    .scaleEffect(isActive ? 1.2 : 1.0)
-    .opacity(isActive ? 1.0 : 0.6)
-    .animation(.bouncy, value: isActive)
+withAnimation(.smooth(duration: 0.4), completionCriteria: .logicallyComplete) {
+    drawerOpen = true
+} completion: {
+    loadDrawerContents()
+}
 ```
 
-## Spring Type (iOS 17+)
+## Implicit animation
 
-Four initializer forms for different mental models.
+- `.animation(_:body:)` (iOS 17) animates only the modifiers inside its body.
+  Prefer it when some modifiers should move and others should not.
+- `.animation(_:value:)` animates every animatable modifier on the view when
+  `value` changes. Fine when one value drives everything.
 
 ```swift
-// Perceptual (preferred)
-Spring(duration: 0.5, bounce: 0.3)
+Image(systemName: "heart.fill")
+    .foregroundStyle(isFavorite ? .pink : .gray)        // changes instantly
+    .animation(.snappy) { content in
+        content
+            .scaleEffect(isFavorite ? 1.25 : 1)
+            .opacity(isFavorite ? 1 : 0.6)
+    }
+
+RoundedRectangle(cornerRadius: 8)
+    .scaleEffect(isRecording ? 1.1 : 1)
+    .opacity(isRecording ? 1 : 0.5)
+    .animation(.bouncy, value: isRecording)
+```
 
-// Physical
-Spring(mass: 1.0, stiffness: 100.0, damping: 10.0)
+## Spring (iOS 17+)
 
-// Response-based
-Spring(response: 0.5, dampingRatio: 0.7)
+`Spring` describes the physics on its own, so the same spring can drive
+`Animation`, `CASpringAnimation` or your own math. Four ways to build one:
 
-// Settling-based
-Spring(settlingDuration: 1.0, dampingRatio: 0.8)
+```swift
+Spring(duration: 0.4, bounce: 0.2)                 // perceptual: preferred
+Spring(mass: 2.0, stiffness: 150.0, damping: 18.0) // physical
+Spring(response: 0.4, dampingRatio: 0.75)          // response-based
+Spring(settlingDuration: 0.9, dampingRatio: 0.85)  // settling-based
 ```
 
-Three presets mirror Animation presets: `.smooth`, `.snappy`, `.bouncy`.
+It has the same three presets as `Animation`: `.smooth`, `.snappy`, `.bouncy`.
 
 ## PhaseAnimator (iOS 17+)
 
-Cycle through discrete phases with per-phase animation curves.
+Steps through a list of phases, with a separate curve for each step.
 
 ```swift
-enum PulsePhase: CaseIterable {
-    case idle, grow, shrink
-}
-
-struct PulsingDot: View {
-    var body: some View {
-        PhaseAnimator(PulsePhase.allCases) { phase in
-            Circle()
-                .frame(width: 40, height: 40)
-                .scaleEffect(phase == .grow ? 1.4 : 1.0)
-                .opacity(phase == .shrink ? 0.5 : 1.0)
-        } animation: { phase in
-            switch phase {
-            case .idle: .easeIn(duration: 0.2)
-            case .grow: .spring(duration: 0.4, bounce: 0.3)
-            case .shrink: .easeOut(duration: 0.3)
-            }
-        }
+enum Nudge: CaseIterable { case rest, lift, drop }
+
+PhaseAnimator(Nudge.allCases) { phase in
+    Image(systemName: "bell.fill")
+        .scaleEffect(phase == .lift ? 1.3 : 1)
+        .opacity(phase == .drop ? 0.7 : 1)
+} animation: { phase in
+    switch phase {
+    case .rest: .easeIn(duration: 0.2)
+    case .lift: .spring(duration: 0.35, bounce: 0.45)
+    case .drop: .easeOut(duration: 0.25)
     }
 }
 ```
 
-Trigger-based variant runs one cycle per trigger change:
-
-```swift
-PhaseAnimator(PulsePhase.allCases, trigger: tapCount) { phase in
-    // ...
-} animation: { _ in .spring(duration: 0.4) }
-```
+With no trigger it loops forever. `PhaseAnimator(_:trigger:content:animation:)`
+plays the phases once each time `trigger` changes.
 
 ## KeyframeAnimator (iOS 17+)
 
-Animate multiple properties along independent timelines.
+Gives each property its own timeline.
 
 ```swift
-struct AnimValues {
-    var scale: Double = 1.0
-    var yOffset: Double = 0.0
-    var opacity: Double = 1.0
+struct HopValues {
+    var scale = 1.0
+    var lift = 0.0
+    var opacity = 1.0
 }
 
-struct BounceView: View {
-    @State private var trigger = false
-
-    var body: some View {
-        Button { trigger.toggle() } label: {
-            Image(systemName: "star.fill")
-                .font(.largeTitle)
-                .keyframeAnimator(
-                    initialValue: AnimValues(),
-                    trigger: trigger
-                ) { content, value in
-                    content
-                        .scaleEffect(value.scale)
-                        .offset(y: value.yOffset)
-                        .opacity(value.opacity)
-                } keyframes: { _ in
-                    KeyframeTrack(\.scale) {
-                        SpringKeyframe(1.5, duration: 0.3)
-                        CubicKeyframe(1.0, duration: 0.4)
-                    }
-                    KeyframeTrack(\.yOffset) {
-                        CubicKeyframe(-30, duration: 0.2)
-                        CubicKeyframe(0, duration: 0.4)
-                    }
-                    KeyframeTrack(\.opacity) {
-                        LinearKeyframe(0.6, duration: 0.15)
-                        LinearKeyframe(1.0, duration: 0.25)
-                    }
-                }
+Button { hops.toggle() } label: {
+    Image(systemName: "hare.fill")
+        .keyframeAnimator(initialValue: HopValues(), trigger: hops) { view, value in
+            view
+                .scaleEffect(value.scale)
+                .offset(y: value.lift)
+                .opacity(value.opacity)
+        } keyframes: { _ in
+            KeyframeTrack(\.lift) {
+                SpringKeyframe(-40, duration: 0.25)
+                CubicKeyframe(0, duration: 0.3)
+            }
+            KeyframeTrack(\.scale) {
+                LinearKeyframe(1.15, duration: 0.2)
+                SpringKeyframe(1.0, duration: 0.35)
+            }
+            KeyframeTrack(\.opacity) {
+                CubicKeyframe(0.8, duration: 0.2)
+                CubicKeyframe(1.0, duration: 0.35)
+            }
         }
-        .buttonStyle(.plain)
-    }
 }
+.buttonStyle(.plain)
 ```
 
-Keyframe types: `LinearKeyframe` (linear), `CubicKeyframe` (smooth curve),
-`SpringKeyframe` (spring physics), `MoveKeyframe` (instant jump).
+| Keyframe | Interpolation |
+|---|---|
+| `LinearKeyframe` | straight line |
+| `CubicKeyframe` | smooth cubic curve |
+| `SpringKeyframe` | spring physics |
+| `MoveKeyframe` | jumps instantly |
 
-Use `repeating: true` for looping keyframe animations.
+`KeyframeAnimator(initialValue:repeating: true)` loops the whole sequence.
 
-## `@Animatable` Macro
+## @Animatable (Xcode 26 SDK)
 
-Replaces manual `AnimatableData` boilerplate. Attach to any type with
-animatable stored properties.
+The `@Animatable` macro writes the `animatableData` conformance for you.
+Attach it to a type whose stored properties should interpolate. It ships with
+the iOS 26 SDK but is declared available from iOS 13, so it also works in apps
+that deploy to older releases.
 
 ```swift
-// Replaces manual AnimatableData boilerplate
 @Animatable
-struct WaveShape: Shape {
-    var frequency: Double
-    var amplitude: Double
-    var phase: Double
-    @AnimatableIgnored var lineWidth: CGFloat
+struct RippleLine: Shape {
+    var wavelength: Double
+    var height: Double
+    var shift: Double
+    @AnimatableIgnored var strokeWidth: Double
 
     func path(in rect: CGRect) -> Path {
-        // draw wave using frequency, amplitude, phase
+        let samples = stride(from: rect.minX, through: rect.maxX, by: 2).map { x in
+            CGPoint(x: x, y: rect.midY + sin(x / wavelength + shift) * height)
+        }
+        return Path { $0.addLines(samples) }
     }
 }
 ```
 
-Rules:
-- Stored properties must conform to `VectorArithmetic`.
-- Use `@AnimatableIgnored` to exclude non-animatable properties.
-- Computed properties are never included.
+- Every animated stored property must conform to `VectorArithmetic`.
+- `@AnimatableIgnored` keeps a stored property out of the animation.
+- Computed properties are never part of the animatable data.
 
 ## matchedGeometryEffect (iOS 14+)
 
-Synchronize geometry between views for shared-element animations.
+Links the geometry of two views so one appears to become the other. Needs a
+`@Namespace`.
 
 ```swift
-struct HeroView: View {
-    @Namespace private var heroSpace
-    @State private var isExpanded = false
-
-    var body: some View {
-        Group {
-            if isExpanded {
-                Button {
-                    withAnimation(.spring(duration: 0.4, bounce: 0.2)) {
-                        isExpanded = false
-                    }
-                } label: {
-                    DetailCard()
-                        .matchedGeometryEffect(id: "card", in: heroSpace)
-                }
-            } else {
-                Button {
-                    withAnimation(.spring(duration: 0.4, bounce: 0.2)) {
-                        isExpanded = true
-                    }
-                } label: {
-                    ThumbnailCard()
-                        .matchedGeometryEffect(id: "card", in: heroSpace)
-                }
-            }
+@Namespace private var photoSpace
+@State private var enlarged = false
+
+var body: some View {
+    let morph = Animation.spring(duration: 0.45, bounce: 0.15)
+    if enlarged {
+        Button { withAnimation(morph) { enlarged = false } } label: {
+            PhotoDetail(photo: photo)
+                .matchedGeometryEffect(id: photo.id, in: photoSpace)
+        }
+        .buttonStyle(.plain)
+    } else {
+        Button { withAnimation(morph) { enlarged = true } } label: {
+            PhotoThumbnail(photo: photo)
+                .matchedGeometryEffect(id: photo.id, in: photoSpace)
         }
         .buttonStyle(.plain)
     }
 }
 ```
 
-Exactly one view per ID must be visible at a time for the interpolation to work.
+At any instant only one view per id may be visible, or the interpolation has
+nothing single to follow.
 
-## Navigation Zoom Transition (iOS 18+)
+## Navigation zoom (iOS 18+)
 
-Pair `matchedTransitionSource` on the source view with
-`.navigationTransition(.zoom(...))` on the destination.
+Mark the tile with `.matchedTransitionSource(id:in:)` and the pushed screen
+with `.navigationTransition(.zoom(sourceID:in:))`:
 
 ```swift
-struct GalleryView: View {
-    @Namespace private var zoomSpace
-    let items: [GalleryItem]
-
-    var body: some View {
-        NavigationStack {
-            ScrollView {
-                LazyVGrid(columns: [GridItem(.adaptive(minimum: 100))]) {
-                    ForEach(items) { item in
-                        NavigationLink {
-                            GalleryDetail(item: item)
-                                .navigationTransition(
-                                    .zoom(sourceID: item.id, in: zoomSpace)
-                                )
-                        } label: {
-                            ItemThumbnail(item: item)
-                                .matchedTransitionSource(
-                                    id: item.id, in: zoomSpace
-                                )
-                        }
-                    }
+@Namespace private var gallery
+
+NavigationStack {
+    ScrollView {
+        LazyVGrid(columns: [GridItem(.adaptive(minimum: 120))]) {
+            ForEach(photos) { photo in
+                NavigationLink {
+                    PhotoDetail(photo: photo)
+                        .navigationTransition(.zoom(sourceID: photo.id, in: gallery))
+                } label: {
+                    PhotoThumbnail(photo: photo)
+                        .matchedTransitionSource(id: photo.id, in: gallery)
                 }
             }
         }
@@ -311,186 +268,146 @@ struct GalleryView: View {
 }
 ```
 
-Apply `.navigationTransition` on the destination view, not on inner containers.
+`.navigationTransition` goes on the destination view itself, not on something
+nested inside it.
 
-## Transitions (iOS 17+)
+## Transitions
 
-Control how views animate on insertion and removal.
+`.transition()` describes how a view enters and leaves:
 
 ```swift
-if showBanner {
-    BannerView()
-        .transition(.move(edge: .top).combined(with: .opacity))
+if showsToast {
+    ToastView(message: message)
+        .transition(.opacity.combined(with: .move(edge: .top)))
 }
 ```
 
-Built-in types: `.opacity`, `.slide`, `.scale`, `.scale(_:anchor:)`,
-`.move(edge:)`, `.push(from:)`, `.offset(x:y:)`, `.identity`,
-`.blurReplace`, `.blurReplace(_:)`, `.symbolEffect`,
+Built in: `.identity`, `.opacity`, `.scale`, `.scale(_:anchor:)`, `.slide`,
+`.offset(x:y:)`, `.move(edge:)` and `.push(from:)`. iOS 17 added
+`.blurReplace`, `.blurReplace(_:)`, `.symbolEffect` and
 `.symbolEffect(_:options:)`.
 
-Asymmetric transitions:
+Different ways in and out:
 
 ```swift
-.transition(.asymmetric(
-    insertion: .push(from: .bottom),
-    removal: .opacity
-))
+.transition(.asymmetric(insertion: .push(from: .trailing), removal: .scale))
 ```
 
-## ContentTransition (iOS 16+)
+Custom `Transition` types are in the advanced reference.
 
-Animate in-place content changes without insertion/removal.
+## Content transitions
+
+`.contentTransition` animates a change inside a view that stays in place.
+It needs an animation to show anything.
 
 ```swift
-Text("\(score)")
+Text("\(stepCount)")
     .contentTransition(.numericText(countsDown: false))
-    .animation(.snappy, value: score)
+    .animation(.snappy, value: stepCount)
 
-// For SF Symbols
-Image(systemName: isMuted ? "speaker.slash" : "speaker.wave.3")
+Image(systemName: isMuted ? "speaker.slash.fill" : "speaker.wave.2.fill")
     .contentTransition(.symbolEffect(.replace.downUp))
 ```
 
-Types: `.identity`, `.interpolate`, `.opacity`,
-`.numericText(countsDown:)`, `.numericText(value:)`, `.symbolEffect`.
+Kinds: `.identity`, `.interpolate`, `.opacity`, `.numericText(countsDown:)`,
+`.numericText(value:)` (iOS 17), `.symbolEffect` (iOS 17).
 
-## Symbol Effects (iOS 17+)
+## Symbol effects (iOS 17+)
 
-Animate SF Symbols with semantic effects.
+Discrete effects play once when a value changes; indefinite ones run while a
+condition is true.
 
 ```swift
-// Discrete (triggers on value change)
-Image(systemName: "bell.fill")
-    .symbolEffect(.bounce, value: notificationCount)
-
-Image(systemName: "arrow.clockwise")
-    .symbolEffect(.wiggle.clockwise, value: refreshCount)
-
-// Indefinite (active while condition holds)
+Image(systemName: "envelope").symbolEffect(.bounce, value: unreadCount)
+Image(systemName: "bell").symbolEffect(.wiggle.clockwise, value: alertCount)   // iOS 18
+Image(systemName: "mic.fill").symbolEffect(.pulse, isActive: isListening)
+Image(systemName: "lungs.fill").symbolEffect(.breathe, isActive: isResting)   // iOS 18
 Image(systemName: "wifi")
-    .symbolEffect(.pulse, isActive: isSearching)
-
-Image(systemName: "mic.fill")
-    .symbolEffect(.breathe, isActive: isRecording)
-
-// Variable color with chaining
-Image(systemName: "speaker.wave.3.fill")
-    .symbolEffect(
-        .variableColor.iterative.reversing.dimInactiveLayers,
-        options: .repeating,
-        isActive: isPlaying
-    )
+    .symbolEffect(.variableColor.iterative.reversing.dimInactiveLayers,
+                  options: .repeating, isActive: isSearching)
 ```
 
-All effects: `.bounce`, `.pulse`, `.variableColor`, `.scale`, `.appear`,
-`.disappear`, `.replace`, `.breathe`, `.rotate`, `.wiggle`.
-
-Scope: `.byLayer`, `.wholeSymbol`. Direction varies per effect.
+Effects: `.appear`, `.disappear`, `.replace`, `.scale`, `.pulse`, `.bounce`
+and `.variableColor`; iOS 18 adds `.wiggle`, `.rotate` and `.breathe`.
+Most accept a scope, `.byLayer` or `.wholeSymbol`; which directions are
+available depends on the effect.
 
-## Symbol Rendering Modes
+### Rendering modes
 
-Control how SF Symbol layers are colored with `.symbolRenderingMode(_:)`.
+`.symbolRenderingMode(_:)` decides how a symbol's layers are coloured.
 
-| Mode | Effect | When to use |
-|------|--------|-------------|
-| `.monochrome` | Single color applied uniformly (default) | Toolbars, simple icons matching text |
-| `.hierarchical` | Single color with opacity layers for depth | Subtle depth without multiple colors |
-| `.multicolor` | System-defined fixed colors per layer | Weather, file types  -  Apple's intended palette |
-| `.palette` | Custom colors per layer via `.foregroundStyle` | Brand colors, custom multi-color icons |
+| Mode | Result | Good for |
+|---|---|---|
+| `.monochrome` (default) | one colour everywhere | toolbar icons that match text |
+| `.hierarchical` | one colour, layers at stepped opacity | depth without extra colours |
+| `.multicolor` | the symbol's own fixed colours | weather, file types, the intended palette |
+| `.palette` | your colours per layer via `.foregroundStyle(_:_:)` | brand or custom multi-colour icons |
 
 ```swift
-// Hierarchical  -  single tint, opacity layers for depth
-Image(systemName: "speaker.wave.3.fill")
+Image(systemName: "folder.fill.badge.gearshape")
     .symbolRenderingMode(.hierarchical)
-    .foregroundStyle(.blue)
+    .foregroundStyle(.teal)
 
-// Palette  -  custom color per layer
-Image(systemName: "person.crop.circle.badge.plus")
+Image(systemName: "person.2.badge.plus.fill")
     .symbolRenderingMode(.palette)
-    .foregroundStyle(.blue, .green)
+    .foregroundStyle(.indigo, .orange)
 
-// Multicolor  -  system-defined colors
-Image(systemName: "cloud.sun.rain.fill")
+Image(systemName: "cloud.bolt.rain.fill")
     .symbolRenderingMode(.multicolor)
-```
-
-**Variable color:** `.symbolVariableColor(value:)` for percentage-based fill (signal strength, volume):
-
-```swift
-Image(systemName: "wifi")
-    .symbolVariableColor(value: signalStrength) // 0.0-1.0
-```
-
-> **Docs:** [SymbolRenderingMode](https://sosumi.ai/documentation/swiftui/symbolrenderingmode) · [symbolRenderingMode(_:)](https://sosumi.ai/documentation/swiftui/view/symbolrenderingmode(_:))
-
-## Common Mistakes
-
-### 1. Using bare `.animation(_:)` when you need precise scope
-
-```swift
-// TOO BROAD  -  applies when the view changes
-.animation(.easeIn)
-
-// CORRECT  -  bind animation to one value
-.animation(.easeIn, value: isVisible)
 
-// CORRECT  -  scope animation to selected modifiers
-.animation(.easeIn) { content in
-    content.opacity(isVisible ? 1.0 : 0.0)
-}
-```
-
-### 2. Expensive work inside animation closures
-
-Never run heavy computation in `keyframeAnimator` / `PhaseAnimator` content closures  -  they execute every frame. Precompute outside, animate only visual properties.
-
-### 3. Missing reduce motion support
-
-```swift
-@Environment(\.accessibilityReduceMotion) private var reduceMotion
-withAnimation(reduceMotion ? .none : .bouncy) { showDetail = true }
-```
-
-### 4. Multiple matchedGeometryEffect sources
-
-Only one view per ID should be visible at a time. Two visible views with the same ID causes undefined layout.
-
-### 5. Using DispatchQueue or UIView.animate
-
-```swift
-// WRONG
-DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { withAnimation { isVisible = true } }
-// CORRECT
-withAnimation(.spring.delay(0.5)) { isVisible = true }
-```
-
-### 6. Forgetting animation on ContentTransition
-
-```swift
-// WRONG  -  no animation, content transition has no effect
-Text("\(count)").contentTransition(.numericText(countsDown: true))
-// CORRECT  -  pair with animation
-Text("\(count)")
-    .contentTransition(.numericText(countsDown: true))
-    .animation(.snappy, value: count)
+Image(systemName: "cellularbars", variableValue: signalLevel)
 ```
 
-### 7. navigationTransition on wrong view
-
-Apply `.navigationTransition(.zoom(sourceID:in:))` on the outermost destination view, not inside a container.
-
-## Review Checklist
-
-- [ ] Animation curve matches intent (spring for natural, ease for mechanical)
-- [ ] `withAnimation` wraps the state change; implicit animation uses `.animation(_:body:)` for selective modifier scope or `.animation(_:value:)` with an explicit value
-- [ ] `matchedGeometryEffect` has exactly one source per ID; zoom uses matching `id`/`namespace`
-- [ ] `@Animatable` macro used instead of manual `animatableData`
-- [ ] `accessibilityReduceMotion` checked; no `DispatchQueue`/`UIView.animate`
-- [ ] Transitions use `.transition()`; `contentTransition` is paired with animation and uses the narrowest implicit animation scope that fits
-- [ ] Animated state changes on @MainActor; animation-driving types are Sendable
+Symbols with variable colour show a level, such as signal strength or volume,
+from a value between 0.0 and 1.0. The value is passed to the image itself
+through `Image(systemName:variableValue:)`; there is no separate modifier for
+it.
+
+Apple docs:
+[SymbolRenderingMode](https://developer.apple.com/documentation/swiftui/symbolrenderingmode),
+[symbolRenderingMode(_:)](https://developer.apple.com/documentation/swiftui/view/symbolrenderingmode(_:)).
+
+## Common mistakes
+
+1. **Bare `.animation(_:)` with no value.** It animates every change that
+   reaches the view. Use `.animation(_:value:)` or `.animation(_:body:)`.
+2. **Work inside `KeyframeAnimator` or `PhaseAnimator` content.** Those
+   closures run every frame. Compute beforehand; only apply visual modifiers.
+3. **Ignoring Reduce Motion.** Read `@Environment(\.accessibilityReduceMotion)`
+   and pass `.none` (or a gentler curve) when it is on.
+4. **Two visible views sharing a `matchedGeometryEffect` id.** Layout becomes
+   undefined.
+5. **Delaying with `DispatchQueue.main.asyncAfter` plus `withAnimation`, or
+   reaching for `UIView.animate`.** Use `Animation.delay(_:)`, for example
+   `.spring.delay(0.5)`.
+6. **`.contentTransition` with no animation.** Nothing visible happens; add
+   `.animation(_:value:)`.
+7. **`.navigationTransition(.zoom(sourceID:in:))` on an inner container.** Put
+   it on the outermost destination view.
+
+## Review checklist
+
+- [ ] Curve fits the intent: a spring for natural motion, an ease curve for
+      mechanical motion
+- [ ] State changes sit inside `withAnimation`; implicit animation is either
+      scoped with `.animation(_:body:)` or tied to a value with
+      `.animation(_:value:)`
+- [ ] One visible `matchedGeometryEffect` source per id; zoom source and
+      destination share id and namespace
+- [ ] `@Animatable` used instead of hand-written `animatableData`
+- [ ] `accessibilityReduceMotion` respected; no `DispatchQueue` timing, no
+      `UIView.animate`
+- [ ] Insertions and removals use `.transition()`; each `contentTransition`
+      has an animation, with the narrowest implicit scope that works
+- [ ] State that drives animation changes on `@MainActor`, and the types
+      involved are `Sendable`
 
 ## References
 
-- See [references/animation-advanced.md](references/animation-advanced.md) for CustomAnimation protocol, full Spring variants, all Transition types, symbol effect details, Transaction system, UnitCurve types, and performance guidance.
-- Core Animation bridging patterns: [references/core-animation-bridge.md](references/core-animation-bridge.md)
+- [Advanced animation](references/animation-advanced.md): `CustomAnimation`,
+  every `Spring` initializer, `UnitCurve`, deeper `PhaseAnimator` and
+  `KeyframeAnimator` patterns, `Transaction` and `TransactionKey`, all
+  transition types including custom ones, every symbol effect option, Reduce
+  Motion patterns, performance.
+- [Core Animation bridge](references/core-animation-bridge.md): when to drop to
+  `CALayer` animation and how to host it in SwiftUI.