ios-swiftui-architect

iOS SwiftUI Architect

Use for iOS SwiftUI UI structure and component choices. Read the nearest local example before introducing a new pattern.

Start

• Existing project: identify screen model (list/detail/editor/settings/tab), search for nearby examples (rg "TabView\\(", etc.), then read references/components-index.md.
• New app: start with references/app-wiring.md for TabView + NavigationStack + sheets, then expand route/sheet enums as screens appear.
• For scroll-driven reveals, read references/scroll-reveal.md before hand-rolling gestures.

Rules

• Prefer @State, @Binding, @Observable, and @Environment; avoid unnecessary view models.
• If iOS 16 or earlier is supported, use ObservableObject with @StateObject at the owner and @ObservedObject for injection.
• Keep views small, composed, and project-formatted.
• Use .task/.task(id:) with loading/error states; read references/async-state.md for cancellation/debouncing.
• Put shared app services in @Environment; keep feature-local dependencies as explicit inputs.
• Prefer newest SwiftUI APIs that match deployment target and call out minimum OS.
• Maintain legacy patterns only inside legacy files.
• Sheets: prefer .sheet(item:), avoid if let inside sheet bodies, let sheets call dismiss() internally.
• Scroll reveals: derive one normalized progress value from scroll offset instead of parallel gesture state machines when possible.

State Ownership

Scenario	Pattern
Local UI state	@State
Child mutates parent value	@Binding
Root-owned iOS 17+ reference model	@State with @Observable
Injected iOS 17+ observable	explicit stored property
Shared service/config	@Environment(Type.self)
iOS 16 legacy model	@StateObject owner, @ObservedObject injected

Choose ownership first; do not introduce a reference model when value state is enough.

New View Workflow

1. Define state ownership, dependencies, and minimum OS.
2. Sketch hierarchy, routing, and presentation; read navigation/sheet/deeplink refs when complex.
3. Build and verify before widening call-site changes.
4. Add async loading and explicit error/loading UI when needed.
5. Add previews for primary/secondary states and accessibility IDs/labels for interactive UI.
6. Validate build/previews/state propagation/list identity/observation scope. If build fails, fix the exact error before continuing.

Anti-Patterns

• Giant views mixing layout, business logic, networking, routing, and formatting.
• Multiple booleans for exclusive sheets/alerts/destinations.
• Live service calls from body.
• AnyView as a composition escape hatch.
• Defaulting every shared dependency to @EnvironmentObject or a global router.

References

• references/components-index.md
• references/navigationstack.md
• references/sheets.md
• references/deeplinks.md
• references/app-wiring.md
• references/async-state.md
• references/previews.md
• references/performance.md

Use current Apple docs when API availability or platform guidance may have changed. New component refs should be short, actionable, and listed in components-index.md.