Best practices and patterns for building SwiftUI views, navigation, and state management.

Covers state ownership strategies (from @State and @Binding to @Observable on iOS 17+), async/await patterns with .task, and environment injection for shared dependencies
Includes cross-cutting references for NavigationStack routing, sheet presentation, deep linking, and app-level wiring with concrete ownership rules
Provides component-specific guidance via indexed references, with anti-patterns and performance considerations for large or scroll-heavy screens
Workflow-driven approach: define state ownership and dependencies first, sketch hierarchy, implement async loading with explicit states, then validate with previews and builds

SwiftUI UI Patterns

Quick start

Choose a track based on your goal:

Identify the feature or screen and the primary interaction model (list, detail, editor, settings, tabbed).
Find a nearby example in the repo with rg "TabView\(" or similar, then read the closest SwiftUI view.
Apply local conventions: prefer SwiftUI-native state, keep state local when possible, and use environment injection for shared dependencies.
Choose the relevant component reference from references/components-index.md and follow its guidance.
If the interaction reveals secondary content by dragging or scrolling the primary content away, read references/scroll-reveal.md before implementing gestures manually.
Build the view with small, focused subviews and SwiftUI-native data flow.

Start with references/app-wiring.md to wire TabView + NavigationStack + sheets.
Add a minimal AppTab and RouterPath based on the provided skeletons.