@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,474 +1,364 @@
 ---
 name: swiftui-gestures
-description: "Implement, review, or improve SwiftUI gesture handling. Use when adding tap, long press, drag, magnify, or rotate gestures, composing gestures with simultaneously/sequenced/exclusively, managing transient state with @GestureState, resolving parent/child gesture conflicts with highPriorityGesture or simultaneousGesture, building custom Gesture protocol conformances, or migrating from deprecated MagnificationGesture to MagnifyGesture or using the newer RotateGesture."
+description: "SwiftUI gestures: tap, spatial tap, long press, drag, magnify, rotate, composition (simultaneously, sequenced, exclusively), @GestureState, parent/child conflicts via highPriorityGesture and simultaneousGesture, GestureMask, custom Gesture types. Use when implementing, reviewing or improving gesture handling, resolving conflicts, building pinch, rotate or drag interactions, or migrating MagnificationGesture to MagnifyGesture and RotationGesture to RotateGesture."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# SwiftUI Gestures (iOS 26+)
+# SwiftUI Gestures
 
-Review, write, and fix SwiftUI gesture interactions. Apply modern gesture APIs
-with correct composition, state management, and conflict resolution using
-Swift 6.3 patterns.
+Recognizing touches in SwiftUI views on iOS 26 with Swift 6.3: which gesture
+type to use, how to keep transient state honest, and how to stop gestures on
+parents and children from fighting. Worked interactions (pinch-to-zoom with
+pan, rotate plus scale, drag-to-reorder, flick-to-dismiss, press-then-drag,
+UIKit interop and accessibility) are in
+[references/gesture-patterns.md](references/gesture-patterns.md).
 
-## Contents
+## Gesture overview
 
-- [Gesture Overview](#gesture-overview)
-- [TapGesture](#tapgesture)
-- [LongPressGesture](#longpressgesture)
-- [DragGesture](#draggesture)
-- [MagnifyGesture (iOS 17+)](#magnifygesture-ios-17)
-- [RotateGesture (iOS 17+)](#rotategesture-ios-17)
-- [Gesture Composition](#gesture-composition)
-- [`@GestureState`](#gesturestate)
-- [Adding Gestures to Views](#adding-gestures-to-views)
-- [Custom Gesture Protocol](#custom-gesture-protocol)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Gesture Overview
-
-| Gesture | Type | Value | Since |
-|---|---|---|---|
+| Gesture | Kind | Value | Since |
+| --- | --- | --- | --- |
 | `TapGesture` | Discrete | `Void` | iOS 13 |
 | `LongPressGesture` | Discrete | `Bool` | iOS 13 |
+| `SpatialTapGesture` | Discrete | `SpatialTapGesture.Value` (location) | iOS 16 |
 | `DragGesture` | Continuous | `DragGesture.Value` | iOS 13 |
 | `MagnifyGesture` | Continuous | `MagnifyGesture.Value` | iOS 17 |
 | `RotateGesture` | Continuous | `RotateGesture.Value` | iOS 17 |
-| `SpatialTapGesture` | Discrete | `SpatialTapGesture.Value` | iOS 16 |
 
-**Discrete** gestures fire once (`.onEnded`). **Continuous** gestures stream
-updates (`.onChanged`, `.onEnded`, `.updating`).
+A discrete gesture reports once, through `.onEnded`. A continuous gesture
+streams values through `.updating` and `.onChanged`, then finishes with
+`.onEnded`.
 
 ## TapGesture
 
-Recognizes one or more taps. Use the `count` parameter for multi-tap.
-
 ```swift
-// Single, double, and triple tap
-TapGesture()            .onEnded { tapped.toggle() }
-TapGesture(count: 2)    .onEnded { handleDoubleTap() }
-TapGesture(count: 3)    .onEnded { handleTripleTap() }
+Image(systemName: "heart")
+    .gesture(TapGesture(count: 2).onEnded { isFavorite.toggle() })
 
-// Shorthand modifier
-Text("Tap me").onTapGesture(count: 2) { handleDoubleTap() }
+// Shorthand
+Image(systemName: "heart")
+    .onTapGesture(count: 2) { isFavorite.toggle() }
 ```
 
+For a plain single tap that performs an action, use a `Button` instead (see
+Common mistakes).
+
 ## LongPressGesture
 
-Succeeds after the user holds for `minimumDuration`. Fails if finger moves
-beyond `maximumDistance`.
+The press succeeds once the finger has stayed down for `minimumDuration`
+(0.5 seconds unless you say otherwise). It fails if the finger travels further
+than `maximumDistance` first.
 
 ```swift
-// Basic long press (0.5s default)
-LongPressGesture()
-    .onEnded { _ in showMenu = true }
-
-// Custom duration and distance tolerance
-LongPressGesture(minimumDuration: 1.0, maximumDistance: 10)
-    .onEnded { _ in triggerHaptic() }
+struct HoldToConfirm: View {
+    @GestureState private var holding = false
+    @State private var confirmed = false
+
+    var body: some View {
+        Circle()
+            .fill(confirmed ? .green : (holding ? .orange : .gray))
+            .frame(width: 88, height: 88)
+            .scaleEffect(holding ? 1.15 : 1)
+            .animation(.easeOut(duration: 0.2), value: holding)
+            .gesture(
+                LongPressGesture(minimumDuration: 1.2, maximumDistance: 12)
+                    .updating($holding) { pressed, state, _ in state = pressed }
+                    .onEnded { _ in confirmed = true }
+            )
+    }
+}
 ```
 
-With visual feedback via `@GestureState` + `.updating()`:
+The shorthand takes a pressing callback for the same feedback:
 
 ```swift
-@GestureState private var isPressing = false
-
-Circle()
-    .fill(isPressing ? .red : .blue)
-    .scaleEffect(isPressing ? 1.2 : 1.0)
-    .gesture(
-        LongPressGesture(minimumDuration: 0.8)
-            .updating($isPressing) { current, state, _ in state = current }
-            .onEnded { _ in completedLongPress = true }
-    )
+.onLongPressGesture(minimumDuration: 1.2) {
+    confirmed = true
+} onPressingChanged: { pressed in
+    highlight = pressed
+}
 ```
 
-Shorthand: `.onLongPressGesture(minimumDuration:perform:onPressingChanged:)`.
-
 ## DragGesture
 
-Tracks finger movement. `Value` provides `startLocation`, `location`,
-`translation`, `velocity`, and `predictedEndTranslation`.
+`DragGesture.Value` carries `startLocation`, `location`, `translation`,
+`velocity` and `predictedEndTranslation`.
 
 ```swift
-@State private var offset = CGSize.zero
-
-RoundedRectangle(cornerRadius: 16)
-    .fill(.blue)
-    .frame(width: 100, height: 100)
-    .offset(offset)
-    .gesture(
-        DragGesture()
-            .onChanged { value in offset = value.translation }
-            .onEnded { _ in withAnimation(.spring) { offset = .zero } }
-    )
+struct SnapBackTile: View {
+    @State private var shift = CGSize.zero
+
+    var body: some View {
+        RoundedRectangle(cornerRadius: 20)
+            .fill(.indigo)
+            .frame(width: 140, height: 140)
+            .offset(shift)
+            .gesture(
+                DragGesture()
+                    .onChanged { drag in shift = drag.translation }
+                    .onEnded { _ in withAnimation(.spring) { shift = .zero } }
+            )
+    }
+}
 ```
 
-Configure minimum distance and coordinate space:
-
-```swift
-DragGesture(minimumDistance: 20, coordinateSpace: .global)
-```
+`DragGesture(minimumDistance: 20, coordinateSpace: .global)` waits for 20
+points of travel and reports locations in window coordinates.
 
 ## MagnifyGesture (iOS 17+)
 
-Replaces the deprecated `MagnificationGesture`. Tracks pinch-to-zoom scale.
+`MagnifyGesture` supersedes `MagnificationGesture`. Its value exposes
+`magnification`.
+
+Transient zoom that springs back when the fingers lift:
 
 ```swift
-@GestureState private var magnifyBy = 1.0
+@GestureState private var pinch: CGFloat = 1
 
-Image("photo")
-    .resizable().scaledToFit()
-    .scaleEffect(magnifyBy)
+photo
+    .scaleEffect(pinch)
     .gesture(
-        MagnifyGesture()
-            .updating($magnifyBy) { value, state, _ in
-                state = value.magnification
-            }
+        MagnifyGesture().updating($pinch) { current, live, _ in
+            live = current.magnification
+        }
     )
 ```
 
-With persisted scale:
+Zoom that sticks, clamped when the gesture ends:
 
 ```swift
-@State private var currentScale = 1.0
-@GestureState private var gestureScale = 1.0
+@State private var zoom: CGFloat = 1
+@GestureState private var livePinch: CGFloat = 1
 
-Image("photo")
-    .scaleEffect(currentScale * gestureScale)
+photo
+    .scaleEffect(zoom * livePinch)
     .gesture(
         MagnifyGesture(minimumScaleDelta: 0.01)
-            .updating($gestureScale) { value, state, _ in state = value.magnification }
-            .onEnded { value in
-                currentScale = min(max(currentScale * value.magnification, 0.5), 5.0)
+            .updating($livePinch) { current, live, _ in live = current.magnification }
+            .onEnded { final in
+                zoom = min(max(zoom * final.magnification, 0.5), 5.0)
             }
     )
 ```
 
 ## RotateGesture (iOS 17+)
 
-`RotateGesture` is the newer alternative to `RotationGesture`. Tracks two-finger rotation angle.
+`RotateGesture` supersedes `RotationGesture`. Its `rotation` is an `Angle`.
 
 ```swift
-@State private var angle = Angle.zero
+@State private var turned = Angle.zero
+@GestureState private var liveTurn = Angle.zero
 
-Rectangle()
-    .fill(.blue).frame(width: 200, height: 200)
-    .rotationEffect(angle)
+dial
+    .rotationEffect(turned + liveTurn)
     .gesture(
         RotateGesture(minimumAngleDelta: .degrees(1))
-            .onChanged { value in angle = value.rotation }
+            .updating($liveTurn) { current, live, _ in live = current.rotation }
+            .onEnded { final in turned += final.rotation }
     )
 ```
 
-With persisted rotation:
-
-```swift
-@State private var currentAngle = Angle.zero
-@GestureState private var gestureAngle = Angle.zero
-
-Rectangle()
-    .rotationEffect(currentAngle + gestureAngle)
-    .gesture(
-        RotateGesture()
-            .updating($gestureAngle) { value, state, _ in state = value.rotation }
-            .onEnded { value in currentAngle += value.rotation }
-    )
-```
+## Gesture composition
 
-## Gesture Composition
+### simultaneously(with:)
 
-### `.simultaneously(with:)`  -  both gestures recognized at the same time
+Both gestures recognize together. The value is `SimultaneousGesture.Value`,
+with optional `first` and `second`.
 
 ```swift
-let magnify = MagnifyGesture()
-    .onChanged { value in scale = value.magnification }
-
-let rotate = RotateGesture()
-    .onChanged { value in angle = value.rotation }
-
-Image("photo")
-    .scaleEffect(scale)
-    .rotationEffect(angle)
-    .gesture(magnify.simultaneously(with: rotate))
+let pinchAndTwist = MagnifyGesture()
+    .simultaneously(with: RotateGesture())
+    .onChanged { both in
+        liveScale = both.first?.magnification ?? 1
+        liveAngle = both.second?.rotation ?? .zero
+    }
 ```
 
-The value is `SimultaneousGesture.Value` with `.first` and `.second` optionals.
+### sequenced(before:)
 
-### `.sequenced(before:)`  -  first must succeed before second begins
+The second gesture can start only after the first one succeeds.
 
 ```swift
-let longPressBeforeDrag = LongPressGesture(minimumDuration: 0.5)
+let holdThenMove = LongPressGesture(minimumDuration: 0.4)
     .sequenced(before: DragGesture())
-    .onEnded { value in
-        guard case .second(true, let drag?) = value else { return }
-        finalOffset.width += drag.translation.width
-        finalOffset.height += drag.translation.height
+    .onEnded { outcome in
+        if case .second(true, let drag?) = outcome {
+            anchor.x += drag.translation.width
+            anchor.y += drag.translation.height
+        }
     }
 ```
 
-### `.exclusively(before:)`  -  only one succeeds (first has priority)
+### exclusively(before:)
+
+Only one gesture wins, and the first one listed gets priority. Map both to a
+shared type to keep the handler simple:
 
 ```swift
-let doubleTapOrLongPress = TapGesture(count: 2)
-    .map { ExclusiveResult.doubleTap }
-    .exclusively(before:
-        LongPressGesture()
-            .map { _ in ExclusiveResult.longPress }
-    )
+enum CardAction { case open, archive }
+
+let openOrArchive = TapGesture(count: 2).map { CardAction.archive }
+    .exclusively(before: TapGesture().map { CardAction.open })
     .onEnded { result in
         switch result {
-        case .first(let val): handleDoubleTap()
-        case .second(let val): handleLongPress()
+        case .first(let action), .second(let action):
+            handle(action)
         }
     }
 ```
 
-## `@GestureState`
+## @GestureState
 
-`@GestureState` is a property wrapper that **automatically resets** to its
-initial value when the gesture ends. Use for transient feedback; use `@State`
-for values that persist.
+`@GestureState` returns to its initial value on its own when the gesture ends
+or is cancelled. Use it for feedback that only exists while a finger is down.
+Keep anything that must survive the gesture in `@State`.
 
 ```swift
-@GestureState private var dragOffset = CGSize.zero  // resets to .zero
-@State private var position = CGSize.zero            // persists
-
-Circle()
-    .offset(
-        x: position.width + dragOffset.width,
-        y: position.height + dragOffset.height
-    )
-    .gesture(
-        DragGesture()
-            .updating($dragOffset) { value, state, _ in
-                state = value.translation
-            }
-            .onEnded { value in
-                position.width += value.translation.width
-                position.height += value.translation.height
-            }
-    )
+struct DraggableSticker: View {
+    @State private var resting = CGPoint(x: 160, y: 300)
+    @GestureState private var inFlight = CGSize.zero
+
+    var body: some View {
+        Text("Sticker")
+            .padding()
+            .background(.yellow, in: .capsule)
+            .position(x: resting.x + inFlight.width, y: resting.y + inFlight.height)
+            .gesture(
+                DragGesture()
+                    .updating($inFlight) { drag, state, _ in state = drag.translation }
+                    .onEnded { drag in
+                        resting.x += drag.translation.width
+                        resting.y += drag.translation.height
+                    }
+            )
+    }
+}
 ```
 
-Custom reset with animation: `@GestureState(resetTransaction: Transaction(animation: .spring))`
+To animate the reset, give the state a reset transaction:
 
-## Adding Gestures to Views
+```swift
+@GestureState(resetTransaction: Transaction(animation: .spring)) private var inFlight = CGSize.zero
+```
 
-Three modifiers control gesture priority in the view hierarchy:
+## Adding gestures to views
 
-| Modifier | Behavior |
-|---|---|
-| `.gesture()` | Default priority. Child gestures win over parent. |
-| `.highPriorityGesture()` | Parent gesture takes precedence over child. |
-| `.simultaneousGesture()` | Both parent and child gestures fire. |
+| Modifier | Who wins when parent and child both recognize |
+| --- | --- |
+| `.gesture(_:)` | The child. Gestures on subviews take precedence. |
+| `.highPriorityGesture(_:)` | The parent's gesture, ahead of the child's. |
+| `.simultaneousGesture(_:)` | Both fire. |
 
-```swift
-// Problem: parent tap swallows child tap
-VStack {
-    Button("Child") { handleChild() }  // never fires
-}
-.gesture(TapGesture().onEnded { handleParent() })
+A typical conflict: a card attaches `.gesture(TapGesture()...)` to open a
+detail screen, and a `Button` inside the card toggles a bookmark. With plain
+`.gesture`, the button keeps priority, so a tap on it never reaches the card's
+handler. Choose deliberately:
 
-// Fix 1: Use simultaneousGesture on parent
-VStack {
-    Button("Child") { handleChild() }
-}
-.simultaneousGesture(TapGesture().onEnded { handleParent() })
+```swift
+// The card should also react when the button is tapped (for example, to log the interaction):
+card.simultaneousGesture(TapGesture().onEnded { logCardTap() })
 
-// Fix 2: Give parent explicit priority
-VStack {
-    Text("Child")
-        .gesture(TapGesture().onEnded { handleChild() })
-}
-.highPriorityGesture(TapGesture().onEnded { handleParent() })
+// The card must take the tap even over its children (the button stops responding):
+card.highPriorityGesture(TapGesture().onEnded { openDetail() })
 ```
 
 ### GestureMask
 
-Control which gestures participate when using `.gesture(_:including:)`:
+`.gesture(_:including:)` narrows which gestures stay active at this level of
+the hierarchy:
+
+| Mask | Effect |
+| --- | --- |
+| `.all` | This gesture and subview gestures (the default) |
+| `.gesture` | Only this gesture; subview gestures are disabled |
+| `.subviews` | Only subview gestures; this gesture is disabled |
+| `.none` | Neither |
 
 ```swift
-.gesture(drag, including: .gesture)   // only this gesture, not subviews
-.gesture(drag, including: .subviews)  // only subview gestures
-.gesture(drag, including: .all)       // default: this + subviews
+canvas.gesture(panGesture, including: isEditing ? .subviews : .all)
 ```
 
-## Custom Gesture Protocol
+## Custom Gesture protocol
 
-Create reusable gestures by conforming to `Gesture`:
+Wrap a configured gesture in its own type by conforming to `Gesture` and
+returning the pieces from `var body: some Gesture`.
 
 ```swift
-struct SwipeGesture: Gesture {
-    enum Direction { case left, right, up, down }
-    let minimumDistance: CGFloat
-    let onSwipe: (Direction) -> Void
-
-    init(minimumDistance: CGFloat = 50, onSwipe: @escaping (Direction) -> Void) {
-        self.minimumDistance = minimumDistance
-        self.onSwipe = onSwipe
-    }
+enum FlingDirection { case left, right, up, down }
+
+struct FlingGesture: Gesture {
+    var threshold: CGFloat = 50
+    var onFling: (FlingDirection) -> Void
 
     var body: some Gesture {
-        DragGesture(minimumDistance: minimumDistance)
-            .onEnded { value in
-                let h = value.translation.width, v = value.translation.height
-                if abs(h) > abs(v) {
-                    onSwipe(h > 0 ? .right : .left)
+        DragGesture(minimumDistance: threshold)
+            .onEnded { drag in
+                let dx = drag.translation.width
+                let dy = drag.translation.height
+                if abs(dx) >= abs(dy) {
+                    onFling(dx > 0 ? .right : .left)
                 } else {
-                    onSwipe(v > 0 ? .down : .up)
+                    onFling(dy > 0 ? .down : .up)
                 }
             }
     }
 }
 
-// Usage
-Rectangle().gesture(SwipeGesture { print("Swiped \($0)") })
-```
-
-Wrap in a `View` extension for ergonomic API:
-
-```swift
 extension View {
-    func onSwipe(perform action: @escaping (SwipeGesture.Direction) -> Void) -> some View {
-        gesture(SwipeGesture(onSwipe: action))
+    func onFling(threshold: CGFloat = 50, perform action: @escaping (FlingDirection) -> Void) -> some View {
+        gesture(FlingGesture(threshold: threshold, onFling: action))
     }
 }
 ```
 
-## Common Mistakes
-
-### 1. Conflicting parent/child gestures
-
-```swift
-// DON'T: Parent .gesture() conflicts with child tap
-VStack {
-    Button("Action") { doSomething() }
-}
-.gesture(TapGesture().onEnded { parentAction() })
-
-// DO: Use .simultaneousGesture() or .highPriorityGesture()
-VStack {
-    Button("Action") { doSomething() }
-}
-.simultaneousGesture(TapGesture().onEnded { parentAction() })
-```
-
-### 2. Using `@State` instead of `@GestureState` for transient state
-
-```swift
-// DON'T: @State doesn't auto-reset  -  view stays offset after gesture ends
-@State private var dragOffset = CGSize.zero
-
-DragGesture()
-    .onChanged { value in dragOffset = value.translation }
-    .onEnded { _ in dragOffset = .zero }  // manual reset required
-
-// DO: @GestureState auto-resets when gesture ends
-@GestureState private var dragOffset = CGSize.zero
-
-DragGesture()
-    .updating($dragOffset) { value, state, _ in
-        state = value.translation
-    }
-```
-
-### 3. Not using .updating() for intermediate feedback
-
-```swift
-// DON'T: No visual feedback during long press
-LongPressGesture(minimumDuration: 2.0)
-    .onEnded { _ in showResult = true }
-
-// DO: Provide feedback while pressing
-@GestureState private var isPressing = false
-
-LongPressGesture(minimumDuration: 2.0)
-    .updating($isPressing) { current, state, _ in
-        state = current
-    }
-    .onEnded { _ in showResult = true }
-```
-
-### 4. Using deprecated gesture types on iOS 17+
-
-```swift
-// DON'T: Deprecated since iOS 17
-MagnificationGesture()   // deprecated  -  use MagnifyGesture()
-
-// DO: Use newer gesture types
-MagnifyGesture()         // iOS 17+
-RotateGesture()          // iOS 17+ (newer alternative to RotationGesture)
-```
-
-### 5. Heavy computation in onChanged
-
-```swift
-// DON'T: Expensive work called every frame (~60-120 Hz)
-DragGesture()
-    .onChanged { value in
-        let result = performExpensiveHitTest(at: value.location)
-        let filtered = applyComplexFilter(result)
-        updateModel(filtered)
-    }
-
-// DO: Throttle or defer expensive work
-DragGesture()
-    .onChanged { value in
-        dragPosition = value.location  // lightweight state update only
-    }
-    .onEnded { value in
-        performExpensiveHitTest(at: value.location)  // once at end
-    }
-```
-
-### 6. Using onTapGesture for actions that should be a Button
-
-```swift
-// DON'T: onTapGesture has no accessibility traits, VoiceOver role,
-// Voice Control targeting, Switch Control scanning, or keyboard activation
-Text("Delete")
-    .onTapGesture { deleteItem() }
-
-// DO: Button provides all of these automatically
-Button("Delete", role: .destructive) { deleteItem() }
-
-// DO: For custom visuals, use ButtonStyle instead of onTapGesture
-Button { toggleExpanded() } label: {
-    CardView()
-}
-.buttonStyle(.plain)
-```
-
-Reserve `onTapGesture` for multi-tap (`count: 2+`), tap-location-dependent
-behavior, or adding tap recognition to non-interactive content that already
-has appropriate accessibility traits.
-
-## Review Checklist
-
-- [ ] Correct gesture type: `MagnifyGesture`/`RotateGesture` (not deprecated `Magnification`/`Rotation` variants)
-- [ ] `@GestureState` used for transient values that should reset; `@State` for persisted values
-- [ ] `.updating()` provides intermediate visual feedback during continuous gestures
-- [ ] Parent/child conflicts resolved with `.highPriorityGesture()` or `.simultaneousGesture()`
-- [ ] `onChanged` closures are lightweight  -  no heavy computation every frame
-- [ ] Composed gestures use correct combinator: `simultaneously`, `sequenced`, or `exclusively`
-- [ ] Persisted scale/rotation clamped to reasonable bounds in `onEnded`
-- [ ] Custom `Gesture` conformances use `var body: some Gesture` (not `View`)
-- [ ] Gesture-driven animations use `.spring` or similar for natural deceleration
-- [ ] `GestureMask` considered when mixing gestures across view hierarchy levels
-- [ ] `onTapGesture` only used where `count > 1`, tap location, or coordinate space matters  -  plain single-tap actions use `Button` instead
+## Common mistakes
+
+1. **Parent and child gestures fighting.** A parent's `.gesture` loses to its
+   children. Decide which should win and use `.simultaneousGesture` or
+   `.highPriorityGesture` accordingly.
+2. **`@State` for a drag offset that should not persist.** It needs a manual
+   reset, and a cancelled gesture can leave the view displaced. Use
+   `@GestureState` with `.updating`.
+3. **Long presses with no feedback while held.** Add `.updating` (or
+   `onPressingChanged`) so the user sees the press registering.
+4. **New code on `MagnificationGesture` or `RotationGesture`.** Both are renamed
+   to `MagnifyGesture` and `RotateGesture` and marked for deprecation. The
+   iOS 26 SDK does not warn yet, but new code on iOS 17 or later should use the
+   replacements.
+5. **Heavy work in `onChanged`.** It runs on every touch update, often 60 to
+   120 times a second. Keep it to assignments; move expensive work to
+   `onEnded` or throttle it.
+6. **`onTapGesture` as a button.** It adds no button trait, no VoiceOver
+   action, no Voice Control or Switch Control target and no keyboard
+   activation. Use `Button` (with a role such as `.destructive` where it
+   applies), and `.buttonStyle(.plain)` when the visuals are custom.
+7. **When `onTapGesture` is right.** Multi-tap counts, handlers that need the
+   tap location, or non-interactive content that you have given proper
+   accessibility traits.
+
+## Review checklist
+
+- [ ] `MagnifyGesture` and `RotateGesture`, not the older names
+- [ ] `@GestureState` for transient values, `@State` for persisted ones
+- [ ] Continuous gestures give live feedback through `.updating`
+- [ ] Parent and child conflicts resolved with the right priority modifier
+- [ ] `onChanged` handlers stay light
+- [ ] Combinator matches intent: simultaneous, sequenced or exclusive
+- [ ] Persisted scale and rotation clamped in `onEnded`
+- [ ] Custom gestures expose `var body: some Gesture`
+- [ ] Gesture-driven motion settles with `.spring` or a similar animation
+- [ ] `GestureMask` considered where several hierarchy levels attach gestures
+- [ ] `onTapGesture` used only for counts above one, tap location or coordinate space needs
 
 ## References
 
-- See [references/gesture-patterns.md](references/gesture-patterns.md) for drag-to-reorder, pinch-to-zoom, combined rotate+scale, velocity calculations, and SwiftUI/UIKit gesture interop.
-- [Gesture protocol](https://sosumi.ai/documentation/swiftui/gesture)
-- [TapGesture](https://sosumi.ai/documentation/swiftui/tapgesture)
-- [LongPressGesture](https://sosumi.ai/documentation/swiftui/longpressgesture)
-- [DragGesture](https://sosumi.ai/documentation/swiftui/draggesture)
-- [MagnifyGesture](https://sosumi.ai/documentation/swiftui/magnifygesture)
-- [RotateGesture](https://sosumi.ai/documentation/swiftui/rotategesture)
-- [GestureState](https://sosumi.ai/documentation/swiftui/gesturestate)
-- [Composing SwiftUI gestures](https://sosumi.ai/documentation/swiftui/composing-swiftui-gestures)
-- [Adding interactivity with gestures](https://sosumi.ai/documentation/swiftui/adding-interactivity-with-gestures)
+- [references/gesture-patterns.md](references/gesture-patterns.md)
+- [Gesture](https://developer.apple.com/documentation/swiftui/gesture)
+- [TapGesture](https://developer.apple.com/documentation/swiftui/tapgesture)
+- [LongPressGesture](https://developer.apple.com/documentation/swiftui/longpressgesture)
+- [DragGesture](https://developer.apple.com/documentation/swiftui/draggesture)
+- [MagnifyGesture](https://developer.apple.com/documentation/swiftui/magnifygesture)
+- [RotateGesture](https://developer.apple.com/documentation/swiftui/rotategesture)
+- [GestureState](https://developer.apple.com/documentation/swiftui/gesturestate)
+- [Composing SwiftUI gestures](https://developer.apple.com/documentation/swiftui/composing-swiftui-gestures)
+- [Adding interactivity with gestures](https://developer.apple.com/documentation/swiftui/adding-interactivity-with-gestures)