@mmerterden/multi-agent-pipeline 20.17.1 → 20.18.0

package/pipeline/skills/shared/external/ios-sf-symbols/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: ios-sf-symbols
+description: "SF Symbols in SwiftUI and UIKit: rendering modes, variable values, symbol effects including Draw On and Off, matching weight and scale to text, custom symbols and accessibility labels. Use when picking, styling, animating or reviewing symbols, or building a custom symbol."
+metadata:
+  source: multi-agent-pipeline
+  date_added: "2026-10-08"
+---
+
+# SF Symbols
+
+SF Symbols are vector glyphs drawn to sit with San Francisco text: nine
+weights and three scales that line up with the font, layers that take colour,
+and built-in animations. Using them well is mostly about letting them follow
+the text and the container instead of sizing them by hand.
+
+## Versions and availability
+
+Symbols and symbol features introduced in a given year are not available on
+earlier systems, so check both the symbol's availability in the SF Symbols app
+and the API's introduction version.
+
+| Capability | API | iOS |
+|---|---|---|
+| Rendering modes | `symbolRenderingMode(_:)`, `SymbolRenderingMode` | 15 |
+| Variants | `symbolVariant(_:)`, `SymbolVariants` | 15 |
+| Variable value | `Image(systemName:variableValue:)` | 16 |
+| Symbol effects | `symbolEffect(_:options:value:)`, `symbolEffect(_:options:isActive:)`, `contentTransition(.symbolEffect(...))` | 17 |
+| Wiggle, Rotate, Breathe | `WiggleSymbolEffect`, `RotateSymbolEffect`, `BreatheSymbolEffect` | 18 |
+| Draw On, Draw Off | `DrawOnSymbolEffect`, `DrawOffSymbolEffect` (`.drawOn`, `.drawOff`) | 26 |
+| Variable Draw | `symbolVariableValueMode(_:)` with `.draw` | 26 |
+| Gradient rendering | `symbolColorRenderingMode(_:)` with `.gradient` | 26 |
+
+SF Symbols 7 introduced Draw, Variable Draw and gradients. The current SF
+Symbols app (27 releases) adds semantic search and new symbols. Check
+developer.apple.com/sf-symbols for the current app before relying on a symbol
+that may be new.
+
+## Sizing with text
+
+Symbols take their size and weight from the font, which is what keeps them
+aligned and scaling with Dynamic Type.
+
+```swift
+Label("Downloads", systemImage: "arrow.down.circle")
+    .font(.headline)
+
+Image(systemName: "bell")
+    .font(.body)
+    .imageScale(.large)
+```
+
+- Set size with `.font(...)` and a text style, not `.resizable().frame(...)`.
+  A resized image stops scaling with Dynamic Type and loses weight matching.
+- Use `imageScale(_:)` (small, medium, large) to change emphasis relative to
+  the text without breaking the weight match.
+- Match weight to adjacent text (`.fontWeight(.semibold)` on both).
+- In UIKit, `UIImage.SymbolConfiguration(textStyle:)` or
+  `init(font:scale:)` does the same job.
+
+## Rendering modes
+
+| Mode | What it does | Good for |
+|---|---|---|
+| Monochrome | One colour for every layer | Toolbars, lists, most UI |
+| Hierarchical | One colour, layers at decreasing opacity | Depth without extra colours |
+| Palette | One explicit colour per layer | Brand or status colour pairs |
+| Multicolor | The symbol's intrinsic colours | Weather, files, recognisable objects |
+
+```swift
+Image(systemName: "cloud.sun.rain.fill")
+    .symbolRenderingMode(.hierarchical)
+    .foregroundStyle(.tint)
+
+Image(systemName: "person.crop.circle.badge.checkmark")
+    .symbolRenderingMode(.palette)
+    .foregroundStyle(.green, .secondary)
+```
+
+Gradient rendering (iOS 26) adds a light linear gradient from a single colour
+in any mode: `.symbolColorRenderingMode(.gradient)`. It looks best at larger
+sizes. Prefer system colours in every mode so symbols adapt to dark mode,
+vibrancy and Increase Contrast. Check the automatic choice at small sizes and
+on busy backgrounds, where a different mode may read better.
+
+## Variants
+
+Outline is the default and sits best next to text. Fill gives emphasis and is
+what tab bars prefer; slash marks something unavailable; enclosed shapes help
+legibility at small sizes. Containers often pick the variant (a tab bar
+chooses fill), so set `symbolVariant(_:)` only when the context does not.
+
+## Variable values
+
+A variable value (0 to 1) shows a level: signal, volume, progress.
+
+```swift
+Image(systemName: "wifi", variableValue: strength)
+
+Image(systemName: "thermometer.high", variableValue: level)
+    .symbolVariableValueMode(.draw)
+```
+
+Variable Color changes layer opacity at thresholds; Variable Draw (iOS 26)
+draws the path to the value, which reads more precisely. Use variable values
+to show change, not depth; hierarchical rendering is for depth.
+
+## Effects
+
+Effects tell people that something happened or is happening. Each has a
+meaning; pick by meaning, not by look.
+
+| Effect | Use | Trigger |
+|---|---|---|
+| Bounce | An action happened | `value:` changes |
+| Pulse, Breathe | Ongoing activity | `isActive:` |
+| Variable Color | Progress or connecting | `isActive:` |
+| Wiggle | Draw attention to something easy to miss | `value:` |
+| Rotate | Work in progress, rotating parts | `isActive:` |
+| Scale | Persistent emphasis on a selection | `isActive:` |
+| Appear, Disappear | Show or hide a symbol | `isActive:` or transition |
+| Draw On, Draw Off | Draw in or out along the path (iOS 26) | `isActive:` or transition |
+| Replace, Magic Replace (18) | Swap one symbol for a related one | `contentTransition` |
+
+```swift
+Image(systemName: "bell")
+    .symbolEffect(.bounce, value: unreadCount)
+
+Image(systemName: isMuted ? "speaker.slash" : "speaker.wave.2")
+    .contentTransition(.symbolEffect(.replace))
+
+Image(systemName: "checkmark.circle")
+    .symbolEffect(.drawOff.byLayer, isActive: !isSaved)
+```
+
+Use effects sparingly; several animated symbols on one screen compete. Repeat
+indefinitely only while the condition holds. Respect Reduce Motion: read
+`accessibilityReduceMotion` and drop decorative repeating effects when it is
+on, keeping the state change itself visible. Full effect options and the
+UIKit equivalents are in `references/effects-and-custom-symbols.md`.
+
+## Custom symbols
+
+When no system symbol fits, build one from the SF Symbols template rather than
+drawing an icon from scratch, so it gets weights, scales, rendering modes and
+animations. In short: export the closest system symbol's template from the SF
+Symbols app, edit it in a vector tool, import it back, annotate layers (and
+Draw guide points if it animates), test every effect, export, and add it to an
+asset catalog as a symbol image. Load it with `Image("name")` or
+`UIImage(named:)`. The full process is in the reference.
+
+Symbols that depict Apple products or features cannot be customised; the SF
+Symbols app marks them with an Info badge.
+
+## Accessibility
+
+- Icon-only controls need a label. `Label("Share", systemImage: ...)` gives
+  VoiceOver and overflow menus a title even when only the icon shows.
+- Use `.accessibilityLabel(...)` when the label must differ from visible text,
+  and hide purely decorative symbols with `.accessibilityHidden(true)`.
+- Custom symbols need an accessibility description; VoiceOver cannot infer one.
+- Directional symbols have right-to-left variants; custom symbols need their
+  directionality set when exported.
+
+## Not in app icons
+
+The SF Symbols licence prohibits using symbols, or confusingly similar images,
+in app icons, logos or any trademarked use. Draw the icon's artwork
+separately; see `hig-app-icons`.
+
+## References
+
+- `references/effects-and-custom-symbols.md`: effect options, UIKit API, custom symbol workflow, review checklist.
+- HIG SF Symbols: https://developer.apple.com/design/human-interface-guidelines/sf-symbols
+- SF Symbols app: https://developer.apple.com/sf-symbols/
+- Symbols framework: https://developer.apple.com/documentation/symbols
+- Configuring and displaying symbol images: https://developer.apple.com/documentation/uikit/configuring-and-displaying-symbol-images-in-your-ui
+- Creating custom symbols: https://developer.apple.com/documentation/technologyoverviews/custom-sf-symbols

package/pipeline/skills/shared/external/ios-sf-symbols/evals/evals.json

@@ -0,0 +1,49 @@
+{
+  "skill_name": "ios-sf-symbols",
+  "evals": [
+    {
+      "id": 0,
+      "name": "symbol-misaligned-with-text",
+      "prompt": "In our settings rows the SF Symbol looks too thin and doesn't grow when users pick a larger text size. The code is Image(systemName: \"bell\").resizable().frame(width: 18, height: 18) next to Text(\"Notifications\").font(.body).fontWeight(.semibold). How should it be done?",
+      "expected_output": "Removes resizable and the fixed frame and sizes the symbol through the font (text style) so it scales with Dynamic Type and keeps the weight match; matches the semibold weight; uses imageScale for emphasis; suggests Label so the row has a title for accessibility.",
+      "files": [],
+      "expectations": [
+        "Removes resizable plus fixed frame sizing",
+        "Sizes the symbol with a font or text style so it follows Dynamic Type",
+        "Matches the symbol weight to the adjacent semibold text",
+        "Mentions imageScale for relative emphasis",
+        "Suggests Label or an accessibility label"
+      ]
+    },
+    {
+      "id": 1,
+      "name": "status-and-animation-choices",
+      "prompt": "We show Wi-Fi signal strength, a syncing state, and a 'saved' confirmation with SF Symbols in an iOS 26 app. Which rendering modes and symbol effects should we use for each, with SwiftUI code, and anything to watch for accessibility?",
+      "expected_output": "Signal strength with a variable value (Image(systemName:variableValue:)), optionally Variable Draw via symbolVariableValueMode(.draw) on iOS 26. Syncing as an indefinite effect (pulse, breathe, rotate or variable color) driven by isActive and stopped when sync ends. Saved confirmation as a discrete bounce on a value change or Draw On or Off (iOS 26). Recommends hierarchical or monochrome with system colours, and gating decorative repeating effects on accessibilityReduceMotion.",
+      "files": [],
+      "expectations": [
+        "Uses a variable value for signal strength",
+        "Mentions Variable Draw or symbolVariableValueMode for iOS 26",
+        "Drives the syncing effect with isActive and stops it when done",
+        "Uses a discrete effect (bounce) or Draw for the saved confirmation",
+        "Respects Reduce Motion for repeating effects",
+        "Recommends system colours or an appropriate rendering mode"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "custom-symbol-and-icon",
+      "prompt": "We need a custom 'boarding pass' symbol that animates like system ones, and marketing also wants to reuse it as the app icon. Walk us through it.",
+      "expected_output": "Duplicate a close system symbol as a custom symbol, export a variable template (Ultralight-S, Regular-S, Black-S), keep matching path counts, convert strokes to fills, no hidden paths or effects, align to guides, export SVG with high precision, validate, import, annotate layers and Draw guide points, test all animation presets, add an accessibility description and directionality, add to an asset catalog and load by name. Refuses the app icon reuse because the SF Symbols terms prohibit symbols or look-alikes in app icons and logos, and routes icon work to hig-app-icons.",
+      "files": [],
+      "expectations": [
+        "Starts from Duplicate as Custom Symbol and Export Template",
+        "Explains the variable template with three interpolation sources",
+        "Requires matching paths, filled shapes and validation",
+        "Mentions annotation including Draw guide points and testing animations",
+        "Mentions an accessibility description for the custom symbol",
+        "Says symbols may not be used as the app icon and points to hig-app-icons"
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/ios-sf-symbols/evals/trigger-eval.json

@@ -0,0 +1,22 @@
+[
+  { "query": "Which SF Symbols rendering mode should I use for a multicolor weather icon?", "should_trigger": true },
+  { "query": "Animate the bell symbol when a new notification arrives", "should_trigger": true },
+  { "query": "How do I use Draw On and Draw Off symbol effects on iOS 26?", "should_trigger": true },
+  { "query": "Make the Wi-Fi symbol show signal strength with a variable value", "should_trigger": true },
+  { "query": "Create a custom SF Symbol from a template and annotate its layers", "should_trigger": true },
+  { "query": "Our symbol looks thinner than the text next to it", "should_trigger": true },
+  { "query": "Use palette rendering with two colors on a badge symbol", "should_trigger": true },
+  { "query": "Swap the play symbol for pause with a smooth transition", "should_trigger": true },
+  { "query": "UIImage.SymbolConfiguration for a large headline symbol in UIKit", "should_trigger": true },
+  { "query": "What's new in SF Symbols 7 and 8 for gradients?", "should_trigger": true },
+  { "query": "Design our app icon in Icon Composer", "should_trigger": false },
+  { "query": "Add a Liquid Glass background to the floating button", "should_trigger": false },
+  { "query": "Pick a custom font that supports Dynamic Type", "should_trigger": false },
+  { "query": "Play a success haptic when the save completes", "should_trigger": false },
+  { "query": "Add a spring animation to the card when it expands", "should_trigger": false },
+  { "query": "Load remote images asynchronously in a list", "should_trigger": false },
+  { "query": "Design review of the whole settings screen in dark mode", "should_trigger": false },
+  { "query": "Add VoiceOver rotor support to our custom chart", "should_trigger": false },
+  { "query": "Export vector PDF assets for the onboarding illustrations", "should_trigger": false },
+  { "query": "Build a tab bar with five destinations", "should_trigger": false }
+]

package/pipeline/skills/shared/external/ios-sf-symbols/references/effects-and-custom-symbols.md

@@ -0,0 +1,135 @@
+# Symbol effects, UIKit API and custom symbols
+
+## Contents
+
+1. Effect options
+2. Effects in UIKit
+3. Rendering and configuration in UIKit
+4. Custom symbol workflow
+5. Review checklist
+
+## 1. Effect options
+
+Effects live in the Symbols framework (`SymbolEffect` and its conforming
+types) and are applied with SwiftUI modifiers or UIKit image view methods.
+
+**How an effect is driven** decides the modifier:
+
+- Discrete effects (Bounce, Wiggle) play once each time a value changes:
+  `.symbolEffect(.bounce, value: count)`.
+- Indefinite effects (Pulse, Breathe, Variable Color, Rotate, Scale) run
+  while a condition is true: `.symbolEffect(.pulse, isActive: isSyncing)`.
+- Transition effects (Appear, Disappear, Draw On, Draw Off) animate a symbol
+  in or out: as `isActive` effects, or as a view transition with
+  `.transition(.symbolEffect(.drawOn))`.
+- Content transitions (Replace, Magic Replace) animate one symbol becoming
+  another: `.contentTransition(.symbolEffect(.replace))` on an image whose
+  `systemName` changes.
+
+**Options** (`SymbolEffectOptions`): `.repeating`, `.nonRepeating`,
+`.repeat(_:)` for a count or behaviour, and `.speed(_:)`.
+
+```swift
+Image(systemName: "antenna.radiowaves.left.and.right")
+    .symbolEffect(.variableColor.iterative, options: .repeating, isActive: isConnecting)
+```
+
+**Layer playback.** Many effects can run on the whole symbol or layer by
+layer (`.byLayer`, `.wholeSymbol`). Draw On and Draw Off add `.individually`,
+which draws one layer at a time for a deliberate reveal.
+
+**Replace directions.** `.replace.downUp` (state change), `.replace.upUp`
+(forward progression), `.replace.offUp` (emphasise the next state). Magic
+Replace animates related shapes (a slash drawing on, a badge appearing) and
+falls back to the default replace for unrelated symbols; `.replace.magic(fallback:)` (iOS 18)
+chooses the fallback.
+
+**Removing inherited effects.** `symbolEffectsRemoved(_:)` stops effects
+applied higher in the hierarchy from reaching a subview.
+
+**Choosing well.** Bounce says "this just happened". Pulse and Breathe say
+"this is ongoing" (Breathe also changes size). Wiggle points at something easy
+to miss. Rotate shows work in progress. Scale holds attention on a selection
+until removed. Draw suits progress and directional meaning. One effect per
+message, and stop indefinite effects when the condition ends.
+
+**Reduce Motion.** Read `@Environment(\.accessibilityReduceMotion)` and skip
+decorative or repeating effects when it is true. Keep the outcome visible
+(the new symbol, the changed state) without the movement.
+
+## 2. Effects in UIKit
+
+`UIImageView` carries the same effects:
+
+```swift
+imageView.addSymbolEffect(.bounce)
+imageView.addSymbolEffect(.pulse, options: .repeating)
+imageView.removeSymbolEffect(ofType: .pulse)
+if let muted = UIImage(systemName: "speaker.slash") {
+    imageView.setSymbolImage(muted, contentTransition: .replace)
+}
+```
+
+`removeAllSymbolEffects()` clears everything; completion handlers report when
+a discrete effect finishes.
+
+## 3. Rendering and configuration in UIKit
+
+`UIImage.SymbolConfiguration` composes with `applying(_:)`:
+
+```swift
+let size = UIImage.SymbolConfiguration(textStyle: .headline, scale: .large)
+let palette = UIImage.SymbolConfiguration(paletteColors: [.systemGreen, .secondaryLabel])
+let image = UIImage(systemName: "person.crop.circle.badge.checkmark",
+                    withConfiguration: size.applying(palette))
+```
+
+Other initialisers and modifiers: `init(hierarchicalColor:)`,
+`preferringMulticolor()`, `preferringMonochrome()`, `init(weight:)`,
+`init(pointSize:weight:scale:)`, and on iOS 26 `init(colorRenderingMode:)`
+(gradient) and `init(variableValueMode:)` (draw). Set a view-level default
+with `UIImageView.preferredSymbolConfiguration`.
+
+## 4. Custom symbol workflow
+
+1. In the SF Symbols app, select the closest system symbol and choose File >
+   Duplicate as Custom Symbol, then File > Export Template.
+2. Pick a template: **variable** (three sources, `Ultralight-S`, `Regular-S`,
+   `Black-S`, from which the other weights and scales are interpolated) or
+   **static** (up to 27 explicit variants for a specific weight and scale).
+3. Edit in a vector tool. Keep the same number of paths and control points
+   across the three sources so interpolation works. Convert strokes to filled
+   paths, use flat fills with no effects, close every shape, and do not leave
+   hidden paths (they are picked up as outlines). Keep the `template-version`
+   layer and lock the artboard.
+4. Align with the template guides (baseline, cap height, margins) so the
+   symbol sits with text. Negative side margins are allowed for optical
+   alignment, named like `left-margin-Regular-M`.
+5. Export SVG at 7 or more decimal places, then validate with File > Validate
+   Templates or by adding it to an asset catalog.
+6. Import back into the SF Symbols app and annotate: layer colours or
+   hierarchy levels for the rendering modes, variable-colour order, and for
+   Draw animations the guide points on each layer (placed for Ultralight,
+   Regular and Black and translated across weights).
+7. Test every animation preset; shapes in motion can show seams that the
+   static symbol hides. Drawing whole shapes plus an erase layer, instead of
+   cut-outs, keeps layer information that animations rely on.
+8. Use the component library for badges and enclosures instead of drawing
+   them into the symbol.
+9. Set directionality for right-to-left and give the symbol an accessibility
+   description.
+10. Export and add to the asset catalog as a symbol image; load with
+    `Image("name")` or `UIImage(named:)`.
+
+## 5. Review checklist
+
+- [ ] Sized by font and text style, not by frame; scales with Dynamic Type.
+- [ ] Weight matches adjacent text; scale used for emphasis.
+- [ ] Consistent variant per meaning; fill only where the container wants it.
+- [ ] Rendering mode legible at the size used, in light, dark and Increase Contrast.
+- [ ] Variable values used for change, hierarchical for depth.
+- [ ] Each effect has one clear meaning; indefinite effects stop with their condition.
+- [ ] Decorative motion skipped under Reduce Motion.
+- [ ] Icon-only controls labelled; decorative symbols hidden from VoiceOver.
+- [ ] Symbol and API available on the deployment target.
+- [ ] No symbols in the app icon or logo.

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

@@ -1,6 +1,6 @@
 ---
 name: swiftui-animation
-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."
+description: "SwiftUI motion: withAnimation, springs, PhaseAnimator, KeyframeAnimator, matched geometry and zoom transitions, scrollTransition and visualEffect, custom transitions, Reduce Motion. Use when implementing, reviewing or improving SwiftUI animations, transitions or scroll-linked effects."
 metadata:
   source: multi-agent-pipeline
 ---
@@ -24,7 +24,9 @@ release an API first shipped in.
 | 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()` |
+| An SF Symbol reacting | symbol effects: `ios-sf-symbols` |
+| Items reacting to their position in a scroll view | `.scrollTransition` |
+| An effect driven by the view's own geometry (parallax) | `.visualEffect` |
 | A timing curve no built-in covers | `CustomAnimation` |
 
 ### 2. Pick the curve
@@ -312,60 +314,39 @@ Image(systemName: isMuted ? "speaker.slash.fill" : "speaker.wave.2.fill")
 Kinds: `.identity`, `.interpolate`, `.opacity`, `.numericText(countsDown:)`,
 `.numericText(value:)` (iOS 17), `.symbolEffect` (iOS 17).
 
-## Symbol effects (iOS 17+)
+Symbol effects (`.symbolEffect`, its options and Reduce Motion handling): `ios-sf-symbols`.
 
-Discrete effects play once when a value changes; indefinite ones run while a
-condition is true.
+## Scroll-driven effects (iOS 17+)
 
-```swift
-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(.variableColor.iterative.reversing.dimInactiveLayers,
-                  options: .repeating, isActive: isSearching)
-```
-
-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.
-
-### Rendering modes
-
-`.symbolRenderingMode(_:)` decides how a symbol's layers are coloured.
-
-| 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 |
+`.scrollTransition` changes a view as it enters and leaves the visible part of
+a scroll view; `.visualEffect` applies effects computed from the view's
+geometry. Neither changes layout, so both are cheap per frame.
 
 ```swift
-Image(systemName: "folder.fill.badge.gearshape")
-    .symbolRenderingMode(.hierarchical)
-    .foregroundStyle(.teal)
-
-Image(systemName: "person.2.badge.plus.fill")
-    .symbolRenderingMode(.palette)
-    .foregroundStyle(.indigo, .orange)
-
-Image(systemName: "cloud.bolt.rain.fill")
-    .symbolRenderingMode(.multicolor)
+ForEach(destinations) { destination in
+    DestinationCard(destination: destination)
+        .scrollTransition { content, phase in
+            content
+                .opacity(phase.isIdentity ? 1 : 0.4)
+                .scaleEffect(phase.isIdentity ? 1 : 0.92)
+        }
+}
 
-Image(systemName: "cellularbars", variableValue: signalLevel)
+HeroImage()
+    .visualEffect { content, proxy in
+        content.offset(y: max(0, proxy.frame(in: .scrollView).minY) / -2)
+    }
 ```
 
-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.
+- `phase.value` runs from -1 (top or leading edge) through 0 (visible) to 1
+  (bottom or trailing edge). Leave the view unchanged at `.identity`.
+- The closures are `@Sendable`: capture values before them rather than reading
+  view state inside.
+- Under Reduce Motion keep opacity, drop movement and parallax, or pass
+  `.identity` as the configuration.
 
-Apple docs:
-[SymbolRenderingMode](https://developer.apple.com/documentation/swiftui/symbolrenderingmode),
-[symbolRenderingMode(_:)](https://developer.apple.com/documentation/swiftui/view/symbolrenderingmode(_:)).
+Configurations, thresholds, the effects available and parallax recipes:
+[references/scroll-effects.md](references/scroll-effects.md).
 
 ## Common mistakes
 
@@ -384,6 +365,8 @@ Apple docs:
    `.animation(_:value:)`.
 7. **`.navigationTransition(.zoom(sourceID:in:))` on an inner container.** Put
    it on the outermost destination view.
+8. **Parallax from `GeometryReader` and `@State` offsets.** Use
+   `.visualEffect`, which does not invalidate the view on every scroll tick.
 
 ## Review checklist
 
@@ -397,6 +380,8 @@ Apple docs:
 - [ ] `@Animatable` used instead of hand-written `animatableData`
 - [ ] `accessibilityReduceMotion` respected; no `DispatchQueue` timing, no
       `UIView.animate`
+- [ ] Scroll-linked effects use `.scrollTransition` or `.visualEffect`, leave
+      the identity phase untouched and drop movement under Reduce Motion
 - [ ] 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
@@ -407,7 +392,10 @@ Apple docs:
 - [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.
+  transition types including custom ones, Reduce Motion patterns,
+  performance.
+- [Scroll effects](references/scroll-effects.md): `scrollTransition` phases,
+  configurations and thresholds, `visualEffect` with `GeometryProxy`,
+  parallax, Sendable closures, Reduce Motion.
 - [Core Animation bridge](references/core-animation-bridge.md): when to drop to
   `CALayer` animation and how to host it in SwiftUI.

package/pipeline/skills/shared/external/swiftui-animation/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "swiftui-animation",
+  "evals": [
+    {
+      "id": 0,
+      "name": "carousel-scroll-transition",
+      "prompt": "Horizontal destination carousel in SwiftUI (iOS 17+). Right now we use a GeometryReader in every card plus an @State offset dictionary to scale and tilt cards toward the edges, and scrolling stutters on older iPhones. Rewrite it properly, and make sure it is fine for people who turn on Reduce Motion.",
+      "expected_output": "Replaces the GeometryReader and state with .scrollTransition(axis: .horizontal) using ScrollTransitionPhase: scale and rotation driven by phase.value or isIdentity, no change in the identity phase, effects limited to visual effects. Optionally uses .scrollTargetBehavior(.viewAligned) with scrollTargetLayout. Reads accessibilityReduceMotion and keeps only opacity or passes .identity configuration, dropping rotation and scale. Notes the closure is Sendable so values are captured outside.",
+      "files": [],
+      "expectations": [
+        "Uses .scrollTransition instead of GeometryReader plus @State offsets",
+        "Drives the effect from ScrollTransitionPhase (value or isIdentity) and leaves the identity phase unchanged",
+        "Uses the horizontal axis for the carousel",
+        "Respects accessibilityReduceMotion by dropping rotation/scale or using the .identity configuration",
+        "Explains why it is cheaper: visual effects do not change layout or invalidate state every frame"
+      ]
+    },
+    {
+      "id": 1,
+      "name": "parallax-header",
+      "prompt": "I want the classic stretchy parallax header image at the top of a ScrollView in SwiftUI: when you pull down it stretches, when you scroll up it moves at half speed. iOS 17 minimum. What's the modern way?",
+      "expected_output": "Uses .visualEffect with the GeometryProxy, reading proxy.frame(in: .scrollView).minY, applying offset for half-speed movement and scale for the stretch, without GeometryReader-driven @State. Explains the closure is @Sendable and only visual effects (offset, scale, blur, opacity) are available, not layout. Mentions disabling parallax under Reduce Motion.",
+      "files": [],
+      "expectations": [
+        "Uses .visualEffect with the GeometryProxy",
+        "Reads the position in the scroll view coordinate space (.scrollView)",
+        "Applies offset and scale effects rather than changing frame or padding",
+        "Mentions turning parallax off when accessibilityReduceMotion is on",
+        "Does not rely on GeometryReader plus @State updates on every scroll"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "button-feedback-curve",
+      "prompt": "Code review: Button { withAnimation(.easeInOut(duration: 1.0)) { isLiked.toggle() } } label: { Image(systemName: isLiked ? \"heart.fill\" : \"heart\").scaleEffect(isLiked ? 1.3 : 1).animation(.linear) }. Also there's a DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { withAnimation { showToast = true } } after it. Fix it.",
+      "expected_output": "Replaces the slow ease and bare .animation(.linear) with a spring (.snappy or .bouncy) via withAnimation or .animation(_:value:) or .animation(_:body:), uses .contentTransition(.symbolEffect(.replace)) or a symbol effect for the heart swap, replaces DispatchQueue delay with Animation.delay, and respects Reduce Motion.",
+      "files": [],
+      "expectations": [
+        "Removes the bare .animation(.linear) without a value",
+        "Uses a spring curve such as .snappy or .bouncy for the tap feedback",
+        "Uses a symbol content transition or symbol effect for the heart change",
+        "Replaces DispatchQueue.main.asyncAfter with Animation.delay or an equivalent animation-based delay",
+        "Mentions accessibilityReduceMotion"
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/swiftui-animation/evals/trigger-eval.json

@@ -0,0 +1,22 @@
+[
+  {"query": "cards in my horizontal ScrollView should shrink and fade as they move toward the edges, swiftui", "should_trigger": true},
+  {"query": "stretchy parallax header image in SwiftUI without GeometryReader hacks", "should_trigger": true},
+  {"query": "my heart button animation feels sluggish, what spring should a tap use", "should_trigger": true},
+  {"query": "PhaseAnimator vs KeyframeAnimator for a bouncing notification bell", "should_trigger": true},
+  {"query": "zoom transition from a grid thumbnail into the detail screen in NavigationStack", "should_trigger": true},
+  {"query": "the number label should roll when the count changes, like a ticker", "should_trigger": true},
+  {"query": "how do I make all these scroll animations behave when the user enabled Reduce Motion", "should_trigger": true},
+  {"query": "visualEffect closure gives a Sendable error when I read my @State inside it", "should_trigger": true},
+  {"query": "rows should blur slightly when they're about to scroll off the top", "should_trigger": true},
+  {"query": "custom Transition type for a card flying in from the bottom with rotation", "should_trigger": true},
+  {"query": "glass buttons should morph into each other when the menu expands on iOS 26", "should_trigger": false},
+  {"query": "tab bar should minimize when scrolling down in iOS 26", "should_trigger": false},
+  {"query": "which SF Symbol rendering mode should I use for a multicolor weather icon", "should_trigger": false},
+  {"query": "add haptic feedback when the like button is tapped", "should_trigger": false},
+  {"query": "scroll to a specific message id programmatically in a chat list", "should_trigger": false},
+  {"query": "our list scrolls slowly with 5000 rows, how do I profile SwiftUI body recomputation", "should_trigger": false},
+  {"query": "Lottie vs Rive for an onboarding illustration", "should_trigger": false},
+  {"query": "Jetpack Compose animateFloatAsState spring parameters", "should_trigger": false},
+  {"query": "CSS scroll-driven animations with animation-timeline", "should_trigger": false},
+  {"query": "pull to refresh in a SwiftUI List", "should_trigger": false}
+]