SwiftUI UI Patterns

Lifecycle Position

Phase 3 (Implement — best practices, UI architecture) and Phase 5 (Review — checklist). Core guidelines apply during implementation; review checklist during code review.

When to Use

digraph when { rankdir=TB; node [fontsize=11];

Q [label="What are you building?" shape=diamond]; A1 [label="New SwiftUI view" shape=box]; A2 [label="Reviewing code" shape=box]; A3 [label="App shell / navigation" shape=box]; A4 [label="Specific UI component" shape=box]; B1 [label="Read Core Guidelines\nthen Quick Reference table" shape=box style=filled fillcolor=lightblue]; B2 [label="Use Review Checklist\nat bottom of this file" shape=box style=filled fillcolor=lightblue]; B3 [label="app-wiring.md → navigation.md\n→ sheets-and-routing.md" shape=box style=filled fillcolor=lightblue]; B4 [label="Find component in\nQuick Reference table" shape=box style=filled fillcolor=lightblue];

Q -> A1 [label="feature"]; Q -> A2 [label="review"]; Q -> A3 [label="scaffold"]; Q -> A4 [label="component"];

A1 -> B1; A2 -> B2; A3 -> B3; A4 -> B4; }

Quick Reference — Which Reference to Load

UI Need Reference File

App root shell, TabRouter, dependency graph references/app-wiring.md

Tab architecture, AppTab enum, TabSection references/tabview.md

NavigationStack routing, RouterPath references/navigation.md

Sheet presentation, SheetDestination enum references/sheets-and-routing.md

Lists, ForEach identity, scroll-to-top references/lists.md

ScrollView, chat anchor, horizontal chips references/scroll-patterns.md

LazyVGrid, adaptive/fixed columns references/grids.md

Forms, themed modals, auto-focus references/forms-and-input.md

.searchable, async debounced search references/searchable.md

Toast overlay, auto-dismiss banners references/overlay-toast.md

Bottom composer bar, .safeAreaInset references/input-toolbar.md

iOS 26+ safeAreaBar, top bar references/top-bar.md

@Observable Theme, semantic colors references/theming.md

AsyncImage, QuickLook media viewer references/image-and-media.md

Haptic feedback, HapticManager references/haptics.md

withAnimation, .animation modifier, CustomAnimation references/state-based-animation.md

Keyframe animations, KeyframeTimeline references/keyframe-animation.md

View transitions, matchedTransitionSource, zoom references/view-transitions.md

Transaction control, TransactionKey references/transactions.md

matchedGeometryEffect, geometryGroup references/geometry-sync.md

Animatable protocol, VectorArithmetic references/animatable-data.md

TimelineView, scheduled updates references/timeline-view.md

PhaseAnimator, multi-step sequences references/phase-animation.md

Spring parameters, UnitCurve timing references/timing-and-curves.md

Deep links, URL dispatch, OpenURLAction references/deeplinks.md

ToolbarTitleMenu, principal title references/title-menus.md

NavigationSplitView vs manual split references/split-views.md

.redacted placeholders, ContentUnavailableView references/loading-placeholders.md

Closure-based client struct, store DI references/lightweight-clients.md

Modern API replacements, deprecations references/modern-apis.md

Property wrappers, @Observable, data flow references/state-management.md

View extraction, composition rules references/view-structure.md

Performance optimization, body purity references/performance-patterns.md

Layout patterns, context-agnostic views references/layout-best-practices.md

Text formatting, localizedStandardContains references/text-formatting.md

Templates

Deep linking and App Shortcuts in templates/ — copy and adapt:

• DeepLink.swift — URL-to-enum parser for typed deep link handling

• DeepLinkRouter.swift — @MainActor @Observable navigation router with pending link support, NavigationPath integration, EnvironmentKey injection

• AppShortcuts.swift — Siri App Intents / App Shortcuts for voice and Spotlight integration

• apple-app-site-association — Universal Links JSON template for your domain

Core Guidelines

State Management

• Always prefer @Observable over ObservableObject for new code

• Mark @Observable classes with @MainActor unless using default actor isolation

• Always mark @State and @StateObject as private (makes dependencies clear)

• Never declare passed values as @State or @StateObject

• @State for internal view state, or owned @Observable class

• @Binding only when child needs to modify parent state

• @Bindable for injected @Observable objects needing bindings

• Use let for read-only values; var

• .onChange() for reactive reads

• Nested ObservableObject doesn't work — pass nested objects directly; @Observable handles nesting

Modern APIs

• foregroundStyle() not foregroundColor()

• clipShape(.rect(cornerRadius:)) not cornerRadius()

• Tab API not tabItem()

• Button not onTapGesture() (unless need location/count)

• NavigationStack not NavigationView

• navigationDestination(for:) for type-safe navigation

• Two-parameter onChange(of:) { old, new in } or no-parameter variant

• .sheet(item:) not .sheet(isPresented:) for model-based sheets

• Sheets own their actions and call dismiss() internally

• containerRelativeFrame() or visualEffect() over GeometryReader

• .scrollIndicators(.hidden) not showsIndicators: false

• Avoid UIScreen.main.bounds for sizing

Swift Best Practices

• Use modern Text formatting (.format parameters, not String(format:) )

• Use localizedStandardContains() for user-input filtering

• Use .task modifier for automatic cancellation of async work

• Use .task(id:) for value-dependent async tasks

View Composition

• Prefer modifiers over conditional views for state changes (maintains view identity)

• Extract complex views into separate subviews early

• Keep view body simple and pure (no side effects or complex logic)

• Use @ViewBuilder let content: Content over closure-based content properties

• Separate business logic into testable models

• Action handlers should reference methods, not contain inline logic

• Use relative layout over hard-coded constants

• Views should work in any context (context-agnostic)

Performance

• Pass only needed values to views (not large "config" or "context" objects)

• LazyVStack /LazyHStack for large lists

• Stable identity for ForEach (never .indices for dynamic content)

• Constant number of views per ForEach element

• No inline filtering in ForEach (prefilter and cache)

• No AnyView in list rows

• Check for value changes before assigning state in hot paths

• No object creation in body

Liquid Glass (iOS 26+)

Only adopt when explicitly requested.

• Use glassEffect , GlassEffectContainer , glass button styles

• Apply .glassEffect() after layout and visual modifiers

• Gate with #available(iOS 26, *) and provide fallbacks

• Use glassEffectID with @Namespace for morphing transitions

• See apple-liquid-glass-design skill for full glass API reference

Review Checklist

State Management (see references/state-management.md )

• Using @Observable instead of ObservableObject for new code

• @Observable classes marked with @MainActor (if needed)

• Using @State with @Observable classes (not @StateObject )

• @State and @StateObject properties are private

• Passed values NOT declared as @State or @StateObject

• @Binding only where child modifies parent state

• @Bindable for injected @Observable needing bindings

• Nested ObservableObject avoided (or passed directly to child views)

Modern APIs (see references/modern-apis.md )

• Using foregroundStyle() instead of foregroundColor()

• Using clipShape(.rect(cornerRadius:)) instead of cornerRadius()

• Using Tab API instead of tabItem()

• Using Button instead of onTapGesture() (unless need location/count)

• Using NavigationStack instead of NavigationView

• Avoiding UIScreen.main.bounds

• Using alternatives to GeometryReader when possible

• Button images include text labels for accessibility

Sheets & Navigation (see references/sheets-and-routing.md , references/navigation.md )

• Using .sheet(item:) for model-based sheets

• Sheets own their actions and dismiss internally

• Using navigationDestination(for:) for type-safe navigation

ScrollView (see references/scroll-patterns.md )

• Using ScrollViewReader with stable IDs for programmatic scrolling

• Using .scrollIndicators(.hidden) instead of initializer parameter

Text & Formatting (see references/text-formatting.md )

• Using modern Text formatting (not String(format:) )

• Using localizedStandardContains() for search filtering

View Structure (see references/view-structure.md )

• Using modifiers instead of conditionals for state changes

• Complex views extracted to separate subviews

• Views kept small for performance

• Container views use @ViewBuilder let content: Content

Performance (see references/performance-patterns.md )

• View body kept simple and pure (no side effects)

• Passing only needed values (not large config objects)

• Eliminating unnecessary dependencies

• State updates check for value changes before assigning

• Hot paths minimize state updates

• No object creation in body

• Heavy computation moved out of body

List Patterns (see references/lists.md )

• ForEach uses stable identity (not .indices )

• Constant number of views per ForEach element

• No inline filtering in ForEach

• No AnyView in list rows

Layout (see references/layout-best-practices.md )

• Avoiding layout thrash (deep hierarchies, excessive GeometryReader)

• Gating frequent geometry updates by thresholds

• Business logic separated into testable models

• Action handlers reference methods (not inline logic)

• Using relative layout (not hard-coded constants)

• Views work in any context (context-agnostic)

Animations (see references/state-based-animation.md , references/view-transitions.md , references/keyframe-animation.md )

• Using .animation(_:value:) with value parameter

• Using withAnimation for event-driven animations

• Transitions paired with animations outside conditional structure

• Custom Animatable has explicit animatableData implementation

• Preferring transforms over layout changes for animation performance

• Phase animations for multi-step sequences (iOS 17+)

• Keyframe animations for precise timing (iOS 17+)

• Completion handlers use .transaction(value:) for reexecution

Liquid Glass (iOS 26+)

• #available(iOS 26, *) with fallback for Liquid Glass

• Multiple glass views wrapped in GlassEffectContainer

• .glassEffect() applied after layout/appearance modifiers

• .interactive() only on user-interactable elements

• Shapes and tints consistent across related elements

Cross-References

• apple-liquid-glass-design — Full Liquid Glass API reference, glass button styles, morph transitions

• swift-concurrency — Actors, @MainActor , Sendable , SwiftUI concurrency patterns

• swift-app-lifecycle — Scene structure, app entry points (pairs with app-wiring.md , deeplinks.md )

• swift-networking — Async network patterns (pairs with references/lightweight-clients.md )

• swiftui-26-api — Non-glass iOS 26 APIs (WebView, TextEditor rich text, @Animatable)

• swiftui-input-api — Text fields, pickers, controls, focus management (pairs with references/searchable.md , references/forms-and-input.md )

• swiftui-material-api — Material backgrounds, shapes, stroke patterns