agy-superpowers 5.0.7 → 5.0.9

package/template/agent/skills/mobile-developer/references/ios-rules/layout-best-practices.md

@@ -0,0 +1,266 @@
+# SwiftUI Layout Best Practices Reference
+
+## Table of Contents
+
+- [Relative Layout Over Constants](#relative-layout-over-constants)
+- [Context-Agnostic Views](#context-agnostic-views)
+- [Own Your Container](#own-your-container)
+- [Layout Performance](#layout-performance)
+- [View Logic and Testability](#view-logic-and-testability)
+- [Full-Width Views](#full-width-views)
+- [Action Handlers](#action-handlers)
+- [Summary Checklist](#summary-checklist)
+
+## Relative Layout Over Constants
+
+**Use dynamic layout calculations instead of hard-coded values.**
+
+```swift
+// Good - relative to actual layout
+GeometryReader { geometry in
+    VStack {
+        HeaderView()
+            .frame(height: geometry.size.height * 0.2)
+        ContentView()
+    }
+}
+
+// Avoid - magic numbers that don't adapt
+VStack {
+    HeaderView()
+        .frame(height: 150)  // Doesn't adapt to different screens
+    ContentView()
+}
+```
+
+**Why**: Hard-coded values don't account for different screen sizes, orientations, or dynamic content (like status bars during phone calls).
+
+## Context-Agnostic Views
+
+**Views should work in any context.** Never assume presentation style or screen size.
+
+```swift
+// Good - adapts to given space
+struct ProfileCard: View {
+    let user: User
+    
+    var body: some View {
+        VStack {
+            Image(user.avatar)
+                .resizable()
+                .aspectRatio(contentMode: .fit)
+            Text(user.name)
+            Spacer()
+        }
+        .padding()
+    }
+}
+
+// Avoid - assumes full screen
+struct ProfileCard: View {
+    let user: User
+    
+    var body: some View {
+        VStack {
+            Image(user.avatar)
+                .frame(width: UIScreen.main.bounds.width)  // Wrong!
+            Text(user.name)
+        }
+    }
+}
+```
+
+**Why**: Views should work as full screens, modals, sheets, popovers, or embedded content.
+
+## Own Your Container
+
+**Custom views should own static containers but not lazy/repeatable ones.**
+
+```swift
+// Good - owns static container
+struct HeaderView: View {
+    var body: some View {
+        HStack {
+            Image(systemName: "star")
+            Text("Title")
+            Spacer()
+        }
+    }
+}
+
+// Avoid - missing container
+struct HeaderView: View {
+    var body: some View {
+        Image(systemName: "star")
+        Text("Title")
+        // Caller must wrap in HStack
+    }
+}
+
+// Good - caller owns lazy container
+struct FeedView: View {
+    let items: [Item]
+    
+    var body: some View {
+        LazyVStack {
+            ForEach(items) { item in
+                ItemRow(item: item)
+            }
+        }
+    }
+}
+```
+
+## Layout Performance
+
+### Avoid Layout Thrash
+
+**Minimize deep view hierarchies and excessive layout dependencies.**
+
+```swift
+// Bad - deep nesting, excessive layout passes
+VStack {
+    HStack {
+        VStack {
+            HStack {
+                VStack {
+                    Text("Deep")
+                }
+            }
+        }
+    }
+}
+
+// Good - flatter hierarchy
+VStack {
+    Text("Shallow")
+    Text("Structure")
+}
+```
+
+**Avoid excessive `GeometryReader` and preference chains:**
+
+```swift
+// Bad - multiple geometry readers cause layout thrash
+GeometryReader { outerGeometry in
+    VStack {
+        GeometryReader { innerGeometry in
+            // Layout recalculates multiple times
+        }
+    }
+}
+
+// Good - single geometry reader or use alternatives (iOS 17+)
+containerRelativeFrame(.horizontal) { width, _ in
+    width * 0.8
+}
+```
+
+**Gate frequent geometry updates:**
+
+```swift
+// Bad - updates on every pixel change
+.onPreferenceChange(ViewSizeKey.self) { size in
+    currentSize = size
+}
+
+// Good - gate by threshold
+.onPreferenceChange(ViewSizeKey.self) { size in
+    let difference = abs(size.width - currentSize.width)
+    if difference > 10 {  // Only update if significant change
+        currentSize = size
+    }
+}
+```
+
+## View Logic and Testability
+
+### Keep Business Logic in Services and Models
+
+**Business logic belongs in services and models, not in views.** Views should stay simple and declarative — orchestrating UI state, not implementing business rules. This makes logic independently testable without requiring view instantiation.
+
+> **iOS 17+**: Use `@Observable` with `@State`.
+
+```swift
+@Observable
+final class AuthService {
+    var email = ""
+    var password = ""
+    var isValid: Bool {
+        !email.isEmpty && password.count >= 8
+    }
+
+    func login() async throws {
+        // Business logic here — testable without the view
+    }
+}
+
+struct LoginView: View {
+    @State private var authService = AuthService()
+
+    var body: some View {
+        Form {
+            TextField("Email", text: $authService.email)
+            SecureField("Password", text: $authService.password)
+            Button("Login") {
+                Task {
+                    try? await authService.login()
+                }
+            }
+            .disabled(!authService.isValid)
+        }
+    }
+}
+```
+
+For iOS 16 and earlier, use `ObservableObject` with `@StateObject` -- see `state-management.md` for the legacy pattern.
+
+Avoid embedding business logic directly in view closures (e.g., validation checks inside a `Button` action). This makes logic untestable without view instantiation.
+
+**Note**: This is about making business logic testable, not about enforcing a specific architecture. The key is that logic lives outside views where it can be tested independently.
+
+## Full-Width Views
+
+**When a single view needs to fill the available width, use `.frame(maxWidth: .infinity, alignment:)` instead of wrapping it in a stack with a `Spacer`.**
+
+```swift
+// Good - frame modifier
+Text("Hello")
+    .frame(maxWidth: .infinity, alignment: .leading)
+
+// Avoid - unnecessary stack and spacer
+HStack {
+    Text("Hello")
+    Spacer()
+}
+```
+
+**Why**: `.frame(maxWidth:alignment:)` is a single modifier that clearly communicates intent. Wrapping in an `HStack` with a `Spacer` adds an extra container to the view hierarchy for no benefit.
+
+## Action Handlers
+
+**Separate layout from logic.** View body should reference action methods, not contain inline logic.
+
+```swift
+// Good - action references method
+Button("Publish Project", action: publishService.handlePublish)
+
+// Avoid - multi-line logic in closure
+Button("Publish Project") {
+    isLoading = true
+    apiService.publish(project) { result in /* ... */ }
+}
+```
+
+## Summary Checklist
+
+- [ ] Use relative layout over hard-coded constants
+- [ ] Views work in any context (don't assume screen size)
+- [ ] Custom views own static containers
+- [ ] Avoid deep view hierarchies (layout thrash)
+- [ ] Gate frequent geometry updates by thresholds
+- [ ] Business logic kept in services and models (not in views)
+- [ ] Action handlers reference methods, not inline logic
+- [ ] Use `.frame(maxWidth: .infinity, alignment:)` for full-width views (not `HStack` + `Spacer`)
+- [ ] Avoid excessive `GeometryReader` usage
+- [ ] Use `containerRelativeFrame()` when appropriate

package/template/agent/skills/mobile-developer/references/ios-rules/liquid-glass.md

@@ -0,0 +1,416 @@
+# SwiftUI Liquid Glass Reference (iOS 26+)
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Availability](#availability)
+- [Core APIs](#core-apis)
+- [GlassEffectContainer](#glasseffectcontainer)
+- [Glass Button Styles](#glass-button-styles)
+- [Morphing Transitions](#morphing-transitions)
+- [Modifier Order](#modifier-order)
+- [Complete Examples](#complete-examples)
+- [Fallback Strategies](#fallback-strategies)
+- [Design System Notes](#design-system-notes)
+- [Best Practices](#best-practices)
+- [Checklist](#checklist)
+
+## Overview
+
+Liquid Glass is Apple's new design language introduced in iOS 26. It provides translucent, dynamic surfaces that respond to content and user interaction. This reference covers the native SwiftUI APIs for implementing Liquid Glass effects.
+
+**Only adopt Liquid Glass when explicitly requested by the user.** Do not proactively convert existing UI to glass effects.
+
+## Availability
+
+All Liquid Glass APIs require iOS 26 or later. Always provide fallbacks:
+
+```swift
+if #available(iOS 26, *) {
+    // Liquid Glass implementation
+} else {
+    // Fallback using materials
+}
+```
+
+## Core APIs
+
+### glassEffect Modifier
+
+The primary modifier for applying glass effects to views:
+
+```swift
+.glassEffect(_ style: GlassEffectStyle = .regular, in shape: some Shape = .rect)
+```
+
+#### Basic Usage
+
+```swift
+Text("Hello")
+    .padding()
+    .glassEffect()  // Default regular style, rect shape
+```
+
+#### With Shape
+
+```swift
+Text("Rounded Glass")
+    .padding()
+    .glassEffect(in: .rect(cornerRadius: 16))
+
+Image(systemName: "star")
+    .padding()
+    .glassEffect(in: .circle)
+
+Text("Capsule")
+    .padding(.horizontal, 20)
+    .padding(.vertical, 10)
+    .glassEffect(in: .capsule)
+```
+
+### GlassEffectStyle
+
+#### Prominence Levels
+
+```swift
+.glassEffect(.regular)     // Standard glass appearance
+.glassEffect(.prominent)   // More visible, higher contrast
+```
+
+#### Tinting
+
+Add color tint to the glass:
+
+```swift
+.glassEffect(.regular.tint(.blue))
+.glassEffect(.prominent.tint(.red.opacity(0.3)))
+```
+
+#### Interactivity
+
+Make glass respond to touch/pointer hover:
+
+```swift
+// Interactive glass - responds to user interaction
+.glassEffect(.regular.interactive())
+
+// Combined with tint
+.glassEffect(.regular.tint(.blue).interactive())
+```
+
+**Important**: Only use `.interactive()` on elements that actually respond to user input (buttons, tappable views, focusable elements).
+
+## GlassEffectContainer
+
+Wraps multiple glass elements for proper visual grouping and spacing.
+
+**Glass cannot sample other glass.** The glass material reflects and refracts light by sampling content from an area larger than itself. Nearby glass elements in different containers will produce inconsistent visual results because they cannot sample each other. `GlassEffectContainer` gives grouped elements a shared sampling region, ensuring a consistent appearance.
+
+```swift
+GlassEffectContainer {
+    HStack {
+        Button("One") { }
+            .glassEffect()
+        Button("Two") { }
+            .glassEffect()
+    }
+}
+```
+
+### With Spacing
+
+Control the visual spacing between glass elements:
+
+```swift
+GlassEffectContainer(spacing: 24) {
+    HStack(spacing: 24) {
+        GlassChip(icon: "pencil")
+        GlassChip(icon: "eraser")
+        GlassChip(icon: "trash")
+    }
+}
+```
+
+**Note**: The container's `spacing` parameter should match the actual spacing in your layout for proper glass effect rendering.
+
+> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
+
+## Glass Button Styles
+
+Built-in button styles for glass appearance:
+
+```swift
+// Standard glass button
+Button("Action") { }
+    .buttonStyle(.glass)
+
+// Prominent glass button (higher visibility)
+Button("Primary Action") { }
+    .buttonStyle(.glassProminent)
+```
+
+### Custom Glass Buttons
+
+For more control, apply glass effect manually:
+
+```swift
+Button(action: { }) {
+    Label("Settings", systemImage: "gear")
+        .padding()
+}
+.glassEffect(.regular.interactive(), in: .capsule)
+```
+
+## Morphing Transitions
+
+Create smooth transitions between glass elements using `glassEffectID` and `@Namespace`:
+
+```swift
+struct MorphingExample: View {
+    @Namespace private var animation
+    @State private var isExpanded = false
+
+    var body: some View {
+        GlassEffectContainer {
+            if isExpanded {
+                ExpandedCard()
+                    .glassEffect()
+                    .glassEffectID("card", in: animation)
+            } else {
+                CompactCard()
+                    .glassEffect()
+                    .glassEffectID("card", in: animation)
+            }
+        }
+        .animation(.smooth, value: isExpanded)
+    }
+}
+```
+
+### Requirements for Morphing
+
+1. Both views must have the same `glassEffectID`
+2. Use the same `@Namespace`
+3. Wrap in `GlassEffectContainer`
+4. Apply animation to the container or parent
+
+## Modifier Order
+
+**Critical**: Apply `glassEffect` after layout and visual modifiers:
+
+```swift
+// CORRECT order
+Text("Label")
+    .font(.headline)           // 1. Typography
+    .foregroundStyle(.primary) // 2. Color
+    .padding()                 // 3. Layout
+    .glassEffect()             // 4. Glass effect LAST
+
+// WRONG order - glass applied too early
+Text("Label")
+    .glassEffect()             // Wrong position
+    .padding()
+    .font(.headline)
+```
+
+## Complete Examples
+
+### Toolbar with Glass Buttons
+
+```swift
+struct GlassToolbar: View {
+    var body: some View {
+        if #available(iOS 26, *) {
+            GlassEffectContainer(spacing: 16) {
+                HStack(spacing: 16) {
+                    ToolbarButton(icon: "pencil", action: { })
+                    ToolbarButton(icon: "eraser", action: { })
+                    ToolbarButton(icon: "scissors", action: { })
+                    Spacer()
+                    ToolbarButton(icon: "square.and.arrow.up", action: { })
+                }
+                .padding(.horizontal)
+            }
+        } else {
+            // Fallback toolbar
+            HStack(spacing: 16) {
+                // ... fallback implementation
+            }
+        }
+    }
+}
+
+struct ToolbarButton: View {
+    let icon: String
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: action) {
+            Image(systemName: icon)
+                .font(.title2)
+                .frame(width: 44, height: 44)
+        }
+        .glassEffect(.regular.interactive(), in: .circle)
+    }
+}
+```
+
+### Card with Glass Effect
+
+```swift
+struct GlassCard: View {
+    let title: String
+    let subtitle: String
+
+    var body: some View {
+        if #available(iOS 26, *) {
+            cardContent
+                .glassEffect(.regular, in: .rect(cornerRadius: 20))
+        } else {
+            cardContent
+                .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 20))
+        }
+    }
+
+    private var cardContent: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Text(title)
+                .font(.headline)
+            Text(subtitle)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+        }
+        .padding()
+        .frame(maxWidth: .infinity, alignment: .leading)
+    }
+}
+```
+
+### Segmented Control
+
+```swift
+struct GlassSegmentedControl: View {
+    @Binding var selection: Int
+    let options: [String]
+    @Namespace private var animation
+
+    var body: some View {
+        if #available(iOS 26, *) {
+            GlassEffectContainer(spacing: 4) {
+                HStack(spacing: 4) {
+                    ForEach(options.indices, id: \.self) { index in
+                        Button(options[index]) {
+                            withAnimation(.smooth) {
+                                selection = index
+                            }
+                        }
+                        .padding(.horizontal, 16)
+                        .padding(.vertical, 8)
+                        .glassEffect(
+                            selection == index ? .prominent.interactive() : .regular.interactive(),
+                            in: .capsule
+                        )
+                        .glassEffectID(selection == index ? "selected" : "option\(index)", in: animation)
+                    }
+                }
+                .padding(4)
+            }
+        } else {
+            Picker("Options", selection: $selection) {
+                ForEach(options.indices, id: \.self) { index in
+                    Text(options[index]).tag(index)
+                }
+            }
+            .pickerStyle(.segmented)
+        }
+    }
+}
+```
+
+## Fallback Strategies
+
+### Using Materials
+
+```swift
+if #available(iOS 26, *) {
+    content.glassEffect()
+} else {
+    content.background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
+}
+```
+
+### Available Materials for Fallback
+
+- `.ultraThinMaterial` - Closest to glass appearance
+- `.thinMaterial` - Slightly more opaque
+- `.regularMaterial` - Standard blur
+- `.thickMaterial` - More opaque
+- `.ultraThickMaterial` - Most opaque
+
+### Conditional Modifier Extension
+
+```swift
+extension View {
+    @ViewBuilder
+    func glassEffectWithFallback(
+        _ style: GlassEffectStyle = .regular,
+        in shape: some Shape = .rect,
+        fallbackMaterial: Material = .ultraThinMaterial
+    ) -> some View {
+        if #available(iOS 26, *) {
+            self.glassEffect(style, in: shape)
+        } else {
+            self.background(fallbackMaterial, in: shape)
+        }
+    }
+}
+```
+
+## Design System Notes
+
+### Toolbar Icons
+
+In the new design, toolbar icons use **monochrome rendering** by default. The monochrome palette reduces visual noise and maintains legibility. Use `tint(_:)` only to convey meaning (e.g., a call to action), not for visual effect.
+
+### Sheet Presentations
+
+Partial-height sheets use a Liquid Glass background by default. If you previously used `presentationBackground(_:)` with a custom background, consider removing it to let the new material shine. Sheets can morph out of the glass controls that present them using `navigationZoomTransition`.
+
+### Scroll Edge Effects
+
+An automatic scroll edge effect blurs and fades content under system toolbars to keep controls legible. Remove any custom background-darkening effects behind bar items, as they will interfere.
+
+> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
+
+## Best Practices
+
+### Do
+
+- Use `GlassEffectContainer` for grouped glass elements (glass cannot sample other glass)
+- Apply glass after layout modifiers
+- Use `.interactive()` only on tappable elements
+- Match container spacing with layout spacing
+- Provide material-based fallbacks for older iOS
+- Keep glass shapes consistent within a feature
+- Remove custom `presentationBackground(_:)` on sheets to use the default glass material
+
+### Don't
+
+- Apply glass to every element (use sparingly)
+- Use `.interactive()` on static content
+- Mix different corner radii arbitrarily
+- Forget iOS version checks
+- Apply glass before padding/frame modifiers
+- Nest `GlassEffectContainer` unnecessarily
+- Add custom darkening backgrounds behind toolbars (conflicts with scroll edge effect)
+
+## Checklist
+
+- [ ] `#available(iOS 26, *)` with fallback
+- [ ] `GlassEffectContainer` wraps grouped elements
+- [ ] `.glassEffect()` applied after layout modifiers
+- [ ] `.interactive()` only on user-interactable elements
+- [ ] `glassEffectID` with `@Namespace` for morphing
+- [ ] Consistent shapes and spacing across feature
+- [ ] Container spacing matches layout spacing
+- [ ] Appropriate prominence levels used