agy-superpowers 5.0.8 → 5.0.9

package/template/agent/skills/mobile-developer/references/ios-rules/accessibility-patterns.md

@@ -0,0 +1,215 @@
+# SwiftUI Accessibility Patterns Reference
+
+## Table of Contents
+
+- [Core Principle](#core-principle)
+- [Dynamic Type and @ScaledMetric](#dynamic-type-and-scaledmetric)
+- [Accessibility Traits](#accessibility-traits)
+- [Decorative Images](#decorative-images)
+- [Element Grouping](#element-grouping)
+- [Custom Controls](#custom-controls)
+- [Summary Checklist](#summary-checklist)
+
+## Core Principle
+
+Prefer `Button` over `onTapGesture` for tappable elements. `Button` provides VoiceOver support, focus handling, and proper traits for free.
+
+## Dynamic Type and @ScaledMetric
+
+System text styles scale with Dynamic Type automatically. Prefer built-in styles like `.largeTitle`, `.title`, `.title2`, `.title3`, `.headline`, `.subheadline`, `.body`, `.callout`, `.footnote`, `.caption`, and `.caption2` when they fit your UI:
+
+```swift
+VStack(alignment: .leading) {
+    Text("Inbox")
+        .font(.title2)
+    Text("3 unread messages")
+        .font(.body)
+    Text("Updated just now")
+        .font(.caption)
+}
+```
+
+For custom fonts, use a Dynamic Type-aware font initializer so the text still follows the user's preferred content size:
+
+```swift
+VStack(alignment: .leading) {
+    Text("Article")
+        .font(.custom("SourceSerif4-Semibold", size: 28, relativeTo: .title2))
+    Text("Body copy")
+        .font(.custom("SourceSerif4-Regular", size: 17))
+}
+```
+
+`Font.custom(_:size:relativeTo:)` lets you match a specific text style. `Font.custom(_:size:)` scales relative to the body style. Avoid fixed-size custom fonts for primary content that should respond to Dynamic Type.
+
+For non-text numeric values like padding, spacing, and image sizes, use `@ScaledMetric`:
+
+```swift
+struct ProfileHeader: View {
+    @ScaledMetric private var avatarSize = 60.0
+    @ScaledMetric private var spacing = 12.0
+
+    var body: some View {
+        HStack(spacing: spacing) {
+            Image("avatar")
+                .resizable()
+                .frame(width: avatarSize, height: avatarSize)
+            Text("Username")
+        }
+    }
+}
+```
+
+Specify a `relativeTo` text style when the value should track a specific Dynamic Type style, including for images or icons that should stay proportional to nearby text:
+
+```swift
+struct StatusRow: View {
+    @ScaledMetric(relativeTo: .body) private var iconSize = 18.0
+
+    var body: some View {
+        HStack(spacing: 8) {
+            Image(systemName: "checkmark.circle.fill")
+                .font(.system(size: iconSize))
+            Text("Synced")
+                .font(.custom("AvenirNext-Regular", size: 17, relativeTo: .body))
+        }
+    }
+}
+```
+
+## Accessibility Traits
+
+Use `accessibilityAddTraits` and `accessibilityRemoveTraits` for state-driven traits:
+
+```swift
+Text(item.title)
+    .accessibilityAddTraits(item.isSelected ? [.isSelected, .isButton] : .isButton)
+```
+
+Use `.disabled(true)` to make VoiceOver announce "Dimmed" for non-interactive elements.
+
+## Decorative Images
+
+Use `Image(decorative:bundle:)` when an asset image is purely visual and should not appear in the accessibility tree.
+
+```swift
+Image(decorative: "confetti")
+```
+
+This is appropriate for backgrounds, flourishes, and icons that do not add meaning beyond nearby text.
+
+If the image conveys information, keep it accessible and provide a clear label:
+
+```swift
+Image("receipt")
+    .accessibilityLabel("Receipt")
+```
+
+For non-asset images, such as SF Symbols, hide decorative content with `accessibilityHidden(true)` instead:
+
+```swift
+Image(systemName: "sparkles")
+    .accessibilityHidden(true)
+```
+
+## Element Grouping
+
+### .combine -- Auto-join child labels
+
+```swift
+HStack {
+    Image(systemName: "star.fill")
+    Text("Favorites")
+    Text("(\(count))")
+}
+.accessibilityElement(children: .combine)
+```
+
+VoiceOver reads all child labels as one element, separated by commas.
+
+### .ignore -- Manual label for container
+
+```swift
+HStack {
+    Text(item.name)
+    Spacer()
+    Text(item.price)
+}
+.accessibilityElement(children: .ignore)
+.accessibilityLabel("\(item.name), \(item.price)")
+```
+
+### .contain -- Semantic grouping
+
+```swift
+HStack {
+    ForEach(tabs) { tab in
+        TabButton(tab: tab)
+    }
+}
+.accessibilityElement(children: .contain)
+.accessibilityLabel("Tab bar")
+```
+
+VoiceOver announces the container name when focus enters/exits.
+
+## Custom Controls
+
+### Adjustable controls (increment/decrement)
+
+```swift
+PageControl(selectedIndex: $selectedIndex, pageCount: pageCount)
+    .accessibilityElement()
+    .accessibilityValue("Page \(selectedIndex + 1) of \(pageCount)")
+    .accessibilityAdjustableAction { direction in
+        switch direction {
+        case .increment:
+            guard selectedIndex < pageCount - 1 else { break }
+            selectedIndex += 1
+        case .decrement:
+            guard selectedIndex > 0 else { break }
+            selectedIndex -= 1
+        @unknown default:
+            break
+        }
+    }
+```
+
+### Representing custom views as native controls
+
+When a custom view should behave like a native control for accessibility:
+
+```swift
+HStack {
+    Text(label)
+    Toggle("", isOn: $isOn)
+}
+.accessibilityRepresentation {
+    Toggle(label, isOn: $isOn)
+}
+```
+
+### Label-content pairing
+
+```swift
+@Namespace private var ns
+
+HStack {
+    Text("Volume")
+        .accessibilityLabeledPair(role: .label, id: "volume", in: ns)
+    Slider(value: $volume)
+        .accessibilityLabeledPair(role: .content, id: "volume", in: ns)
+}
+```
+
+## Summary Checklist
+
+- [ ] Use `Button` instead of `onTapGesture` for tappable elements
+- [ ] Use built-in text styles or Dynamic Type-aware custom fonts for text
+- [ ] Use `@ScaledMetric` for custom values that should scale with Dynamic Type
+- [ ] Mark purely decorative images as decorative or hidden from accessibility
+- [ ] Group related elements with `accessibilityElement(children:)`
+- [ ] Provide `accessibilityLabel` when default labels are unclear
+- [ ] Use `accessibilityRepresentation` for custom controls
+- [ ] Use `accessibilityAdjustableAction` for increment/decrement controls
+- [ ] Ensure navigation flow is logical when using VoiceOver grouping

package/template/agent/skills/mobile-developer/references/ios-rules/animation-advanced.md

@@ -0,0 +1,403 @@
+# SwiftUI Advanced Animations
+
+Transactions, phase animations (iOS 17+), keyframe animations (iOS 17+), completion handlers (iOS 17+), and `@Animatable` macro (iOS 26+).
+
+## Table of Contents
+- [Transactions](#transactions)
+- [Phase Animations (iOS 17+)](#phase-animations-ios-17)
+- [Keyframe Animations (iOS 17+)](#keyframe-animations-ios-17)
+- [Animation Completion Handlers (iOS 17+)](#animation-completion-handlers-ios-17)
+- [@Animatable Macro (iOS 26+)](#animatable-macro-ios-26)
+
+---
+
+## Transactions
+
+The underlying mechanism for all animations in SwiftUI.
+
+### Basic Usage
+
+```swift
+// withAnimation is shorthand for withTransaction
+withAnimation(.default) { flag.toggle() }
+
+// Equivalent explicit transaction
+var transaction = Transaction(animation: .default)
+withTransaction(transaction) { flag.toggle() }
+```
+
+### The .transaction Modifier
+
+```swift
+Rectangle()
+    .frame(width: flag ? 100 : 50, height: 50)
+    .transaction { t in
+        t.animation = .default
+    }
+```
+
+**Note:** This behaves like the deprecated `.animation(_:)` without value parameter - it animates on every state change.
+
+### Animation Precedence
+
+**Implicit animations override explicit animations** (later in view tree wins).
+
+```swift
+Button("Tap") {
+    withAnimation(.linear) { flag.toggle() }
+}
+.animation(.bouncy, value: flag)  // .bouncy wins!
+```
+
+### Disabling Animations
+
+```swift
+// Prevent implicit animations from overriding
+.transaction { t in
+    t.disablesAnimations = true
+}
+
+// Remove animation entirely
+.transaction { $0.animation = nil }
+```
+
+### Custom Transaction Keys (iOS 17+)
+
+Pass metadata through transactions.
+
+```swift
+struct ChangeSourceKey: TransactionKey {
+    static let defaultValue: String = "unknown"
+}
+
+extension Transaction {
+    var changeSource: String {
+        get { self[ChangeSourceKey.self] }
+        set { self[ChangeSourceKey.self] = newValue }
+    }
+}
+
+// Set source
+var transaction = Transaction(animation: .default)
+transaction.changeSource = "server"
+withTransaction(transaction) { flag.toggle() }
+
+// Read in view tree
+.transaction { t in
+    if t.changeSource == "server" {
+        t.animation = .smooth
+    } else {
+        t.animation = .bouncy
+    }
+}
+```
+
+---
+
+## Phase Animations (iOS 17+)
+
+Cycle through discrete phases automatically. Each phase change is a separate animation.
+
+### Basic Usage
+
+```swift
+// GOOD - triggered phase animation
+Button("Shake") { trigger += 1 }
+    .phaseAnimator(
+        [0.0, -10.0, 10.0, -5.0, 5.0, 0.0],
+        trigger: trigger
+    ) { content, offset in
+        content.offset(x: offset)
+    }
+
+// Infinite loop (no trigger)
+Circle()
+    .phaseAnimator([1.0, 1.2, 1.0]) { content, scale in
+        content.scaleEffect(scale)
+    }
+```
+
+### Enum Phases (Recommended for Clarity)
+
+```swift
+// GOOD - enum phases are self-documenting
+enum BouncePhase: CaseIterable {
+    case initial, up, down, settle
+
+    var scale: CGFloat {
+        switch self {
+        case .initial: 1.0
+        case .up: 1.2
+        case .down: 0.9
+        case .settle: 1.0
+        }
+    }
+}
+
+Circle()
+    .phaseAnimator(BouncePhase.allCases, trigger: trigger) { content, phase in
+        content.scaleEffect(phase.scale)
+    }
+```
+
+### Custom Timing Per Phase
+
+```swift
+.phaseAnimator([0, -20, 20], trigger: trigger) { content, offset in
+    content.offset(x: offset)
+} animation: { phase in
+    switch phase {
+    case -20: .bouncy
+    case 20: .linear
+    default: .smooth
+    }
+}
+```
+
+### Good vs Bad
+
+```swift
+// GOOD - use phaseAnimator for multi-step sequences
+.phaseAnimator([0, -10, 10, 0], trigger: trigger) { content, offset in
+    content.offset(x: offset)
+}
+
+// BAD - manual DispatchQueue sequencing
+Button("Animate") {
+    withAnimation(.easeOut(duration: 0.1)) { offset = -10 }
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
+        withAnimation { offset = 10 }
+    }
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
+        withAnimation { offset = 0 }
+    }
+}
+```
+
+---
+
+## Keyframe Animations (iOS 17+)
+
+Precise timing control with exact values at specific times.
+
+### Basic Usage
+
+```swift
+Button("Bounce") { trigger += 1 }
+    .keyframeAnimator(
+        initialValue: AnimationValues(),
+        trigger: trigger
+    ) { content, value in
+        content
+            .scaleEffect(value.scale)
+            .offset(y: value.verticalOffset)
+    } keyframes: { _ in
+        KeyframeTrack(\.scale) {
+            SpringKeyframe(1.2, duration: 0.15)
+            SpringKeyframe(0.9, duration: 0.1)
+            SpringKeyframe(1.0, duration: 0.15)
+        }
+        KeyframeTrack(\.verticalOffset) {
+            LinearKeyframe(-20, duration: 0.15)
+            LinearKeyframe(0, duration: 0.25)
+        }
+    }
+
+struct AnimationValues {
+    var scale: CGFloat = 1.0
+    var verticalOffset: CGFloat = 0
+}
+```
+
+### Keyframe Types
+
+| Type | Behavior |
+|------|----------|
+| `CubicKeyframe` | Smooth interpolation |
+| `LinearKeyframe` | Straight-line interpolation |
+| `SpringKeyframe` | Spring physics |
+| `MoveKeyframe` | Instant jump (no interpolation) |
+
+### Multiple Synchronized Tracks
+
+Tracks run **in parallel**, each animating one property.
+
+```swift
+// GOOD - bell shake with synchronized rotation and scale
+struct BellAnimation {
+    var rotation: Double = 0
+    var scale: CGFloat = 1.0
+}
+
+Image(systemName: "bell.fill")
+    .keyframeAnimator(
+        initialValue: BellAnimation(),
+        trigger: trigger
+    ) { content, value in
+        content
+            .rotationEffect(.degrees(value.rotation))
+            .scaleEffect(value.scale)
+    } keyframes: { _ in
+        KeyframeTrack(\.rotation) {
+            CubicKeyframe(15, duration: 0.1)
+            CubicKeyframe(-15, duration: 0.1)
+            CubicKeyframe(10, duration: 0.1)
+            CubicKeyframe(-10, duration: 0.1)
+            CubicKeyframe(0, duration: 0.1)
+        }
+        KeyframeTrack(\.scale) {
+            CubicKeyframe(1.1, duration: 0.25)
+            CubicKeyframe(1.0, duration: 0.25)
+        }
+    }
+
+// BAD - manual timer-based animation
+Image(systemName: "bell.fill")
+    .onTapGesture {
+        withAnimation(.easeOut(duration: 0.1)) { rotation = 15 }
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
+            withAnimation { rotation = -15 }
+        }
+        // ... more manual timing - error prone
+    }
+```
+
+### KeyframeTimeline (iOS 17+)
+
+Query animation values directly for testing or non-SwiftUI use.
+
+```swift
+let timeline = KeyframeTimeline(initialValue: AnimationValues()) {
+    KeyframeTrack(\.scale) {
+        CubicKeyframe(1.2, duration: 0.25)
+        CubicKeyframe(1.0, duration: 0.25)
+    }
+}
+
+let midpoint = timeline.value(time: 0.25)
+print(midpoint.scale)  // Value at 0.25 seconds
+```
+
+---
+
+## Animation Completion Handlers (iOS 17+)
+
+Execute code when animations finish.
+
+### With withAnimation
+
+```swift
+// GOOD - completion with withAnimation
+Button("Animate") {
+    withAnimation(.spring) {
+        isExpanded.toggle()
+    } completion: {
+        showNextStep = true
+    }
+}
+```
+
+### With Transaction (For Reexecution)
+
+```swift
+// GOOD - completion fires on every trigger change
+Circle()
+    .scaleEffect(bounceCount % 2 == 0 ? 1.0 : 1.2)
+    .transaction(value: bounceCount) { transaction in
+        transaction.animation = .spring
+        transaction.addAnimationCompletion {
+            message = "Bounce \(bounceCount) complete"
+        }
+    }
+
+// BAD - completion only fires ONCE (no value parameter)
+Circle()
+    .scaleEffect(bounceCount % 2 == 0 ? 1.0 : 1.2)
+    .animation(.spring, value: bounceCount)
+    .transaction { transaction in  // No value!
+        transaction.addAnimationCompletion {
+            completionCount += 1  // Only fires once, ever
+        }
+    }
+```
+
+---
+
+## @Animatable Macro (iOS 26+)
+
+The `@Animatable` macro auto-synthesizes `animatableData` from all animatable stored properties, eliminating verbose manual conformance. Use `@AnimatableIgnored` to exclude properties that should not animate.
+
+### Before (Manual)
+
+```swift
+struct Wedge: Shape {
+    var startAngle: Angle
+    var endAngle: Angle
+    var drawClockwise: Bool
+
+    var animatableData: AnimatablePair<Double, Double> {
+        get { AnimatablePair(startAngle.radians, endAngle.radians) }
+        set {
+            startAngle = .radians(newValue.first)
+            endAngle = .radians(newValue.second)
+        }
+    }
+
+    func path(in rect: CGRect) -> Path { /* ... */ }
+}
+```
+
+### After (@Animatable)
+
+```swift
+@Animatable
+struct Wedge: Shape {
+    var startAngle: Angle
+    var endAngle: Angle
+    @AnimatableIgnored var drawClockwise: Bool
+
+    func path(in rect: CGRect) -> Path { /* ... */ }
+}
+```
+
+### When to Use
+- **Prefer `@Animatable`** for any custom `Shape`, `AnimatableModifier`, or type conforming to `Animatable` with multiple properties
+- **Use `@AnimatableIgnored`** for properties that control behavior but should not interpolate (e.g., directions, flags, identifiers)
+- The macro works with any type conforming to `Animatable`, not just `Shape`
+
+> Source: "What's new in SwiftUI" (WWDC25, session 256)
+
+---
+
+## Quick Reference
+
+### Transactions (All iOS versions)
+- `withTransaction` is the explicit form of `withAnimation`
+- Implicit animations override explicit (later in view tree wins)
+- Use `disablesAnimations` to prevent override
+- Use `.transaction { $0.animation = nil }` to remove animation
+
+### Custom Transaction Keys (iOS 17+)
+- Pass metadata through animation system via `TransactionKey`
+
+### Phase Animations (iOS 17+)
+- Use for multi-step sequences returning to start
+- Prefer enum phases for clarity
+- Each phase change is a separate animation
+- Use `trigger` parameter for one-shot animations
+
+### Keyframe Animations (iOS 17+)
+- Use for precise timing control
+- Tracks run in parallel
+- Use `KeyframeTimeline` for testing/advanced use
+- Prefer over manual DispatchQueue timing
+
+### Completion Handlers (iOS 17+)
+- Use `withAnimation(.animation) { } completion: { }` for one-shot completion handlers
+- Use `.transaction(value:)` for handlers that should refire on every value change
+- Without `value:` parameter, completion only fires once
+
+### @Animatable Macro (iOS 26+)
+- Use `@Animatable` to auto-synthesize `animatableData` from stored properties
+- Use `@AnimatableIgnored` to exclude non-animatable properties
+- Replaces verbose manual `animatableData` getters/setters