swiftui-advanced skill

---
name: swiftui-advanced
description: Use when implementing gesture composition (simultaneous, sequenced, exclusive), adaptive layouts (ViewThatFits, AnyLayout, size classes), or choosing architecture patterns (MVVM vs TCA vs vanilla, State-as-Bridge). Covers advanced SwiftUI patterns beyond basic views.
---

# SwiftUI Advanced

Advanced SwiftUI patterns for gesture composition, adaptive layouts, architecture decisions, and performance optimization.

## Reference Loading Guide

**ALWAYS load reference files if there is even a small chance the content may be required.** It's better to have the context than to miss a pattern or make a mistake.

| Reference | Load When |
|-----------|-----------|
| **[Gestures](references/gestures.md)** | Composing multiple gestures, GestureState, custom recognizers |
| **[Adaptive Layout](references/adaptive-layout.md)** | ViewThatFits, AnyLayout, size classes, iOS 26 free-form windows |
| **[Architecture](references/architecture.md)** | MVVM vs TCA decision, State-as-Bridge, property wrapper selection |
| **[Performance](references/performance.md)** | Instruments 26, view body optimization, unnecessary updates |

## Core Workflow

1. **Identify pattern category** from user's question
2. **Load relevant reference** for detailed patterns and code examples
3. **Apply pattern** following the decision trees and anti-patterns
4. **Verify** using provided checklists or profiling guidance

## Decision Trees

### Gesture Composition
- Both gestures at same time? -> `.simultaneously`
- One must complete before next? -> `.sequenced`
- Only one should win? -> `.exclusively`

### Layout Adaptation
- Pick best-fitting variant? -> `ViewThatFits`
- Animated H/V switch? -> `AnyLayout`
- Need actual dimensions? -> `onGeometryChange`

### Architecture Selection
- Small app, Apple patterns? -> @Observable + State-as-Bridge
- Complex presentation logic? -> MVVM with @Observable
- Rigorous testability needed? -> TCA

## Common Mistakes

1. **Gesture composition order matters** — `.simultaneously` and `.sequenced` have different trigger timing. Swapping them silently changes behavior. Understand gesture semantics before using.

2. **ViewThatFits over-used** — ViewThatFits remeasures on every view change. For animated H/V switches, use `AnyLayout` instead. Use ViewThatFits only for static variant selection.

3. **onGeometryChange triggering unnecessary updates** — Reading geometry changes geometry, which triggers updates, which changes geometry... circular. Use `.onGeometryChange` only with proper state management to avoid loops.

4. **Architecture mismatch mid-project** — Starting with @Observable + State-as-Bridge then realizing you need TCA is expensive. Choose architecture upfront based on complexity (small app = @Observable, complex = TCA).

5. **Ignoring view body optimization** — Computing expensive calculations in view body repeatedly kills performance. Move calculations to properties or models. Profile with Instruments 26 before optimizing prematurely.