/swiftui-patterns

name: swiftui-patterns
description: "Builds and reviews SwiftUI views with modern MV architecture, state, composition, isolated previews, and migration guidance. Covers @Observable ownership, @State/@Bindable/@Environment wiring, view decomposition, ViewModifiers, environment values, .task loading, iOS 26+ handoffs, Writing Tools, clipboard availability, and performance. Use when structuring SwiftUI state, managing @Observable, composing views, previewing meaningful UI states, or correcting SwiftUI patterns."

SwiftUI Patterns

Modern SwiftUI patterns targeting iOS 26+ with Swift 6.3. Covers architecture, state management, view composition, environment wiring, async loading, design polish, and platform/share integration. Navigation, layout, animation, and Liquid Glass patterns live in dedicated sibling skills. Patterns are backward-compatible to iOS 17 unless noted.

Contents

• [Architecture: Model-View (MV) Pattern](#architecture-model-view-mv-pattern)
• [Workflow](#workflow)
• [State Management](#state-management)
• [View Ordering Convention](#view-ordering-convention)
• [View Composition](#view-composition)
• [Environment](#environment)
• [Async Data Loading](#async-data-loading)
• [iOS 26+ New APIs](#ios-26-new-apis)
• [Performance Guidelines](#performance-guidelines)
• [HIG Alignment](#hig-alignment)
• [Writing Tools (iOS 18+)](#writing-tools-ios-18)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

**Scope boundary:** This skill covers architecture, state ownership, composition, environment wiring, async loading, and related SwiftUI app structure patterns. Detailed navigation patterns are covered in the `swiftui-navigation` skill, including `NavigationStack`, `NavigationSplitView`, sheets, tabs, and deep-linking patterns. Detailed layout, container, and component patterns are covered in the `swiftui-layout-components` skill, including stacks, grids, lists, scroll view patterns, forms, controls, search UI with `.searchable`, overlays, and related layout components. Detailed animation choreography is covered in `swiftui-animation`. Liquid Glass adoption, custom glass controls, scroll edge effects, `.scrollEdgeEffectStyle`, and `.backgroundExtensionEffect` are covered in `swiftui-liquid-glass`.

Workflow

1. Record the current state ownership, actions, side effects, navigation, and lifecycle behavior. 2. Choose the smallest MV/state/composition change that preserves that contract. 3. Build after each structural step; fix compiler and isolation errors before continuing. 4. Render deterministic previews for loaded, loading, empty, and error states as applicable, including required environment dependencies. 5. Exercise important interactions and side effects. If behavior changes, restore the fixture, fix the smallest boundary, and rerun the same build, preview, and interaction checks.

Load [Behavior-Preserving View Refactoring](references/view-refactoring.md) for restructuring existing views and [Isolated Preview Construction](references/preview-isolation.md) for fixture and dependency patterns.

Architecture: Model-View (MV) Pattern

Default to MV -- views are lightweight state expressions; models and services own business logic. Do not introduce view models unless the existing code already uses them.

**Core principles:**

• Favor `@State`, `@Environment`, `@Query`, `.task`, and `.onChange` for orchestration
• Inject services and shared models via `@Environment`; keep views small and composable
• Split large views into smaller subviews rather than introducing a view model
• Test models, services, and business logic; keep views simple and declarative

struct FeedView: View {
    @Environment(FeedClient.self) private var client

    enum ViewState {
        case loading, error(String), loaded([Post])
    }

    @State private var viewState: ViewState = .loading

    var body: some View {
        List {
            switch viewState {
            case .loading:
                ProgressView()
            case .error(let message):
                ContentUnavailableView("Error", systemImage: "exclamationmark.triangle",
                                       description: Text(message))
            case .loaded(let posts):
                ForEach(posts) { post in
                    PostRow(post: post)
                }
            }
        }
        .task { await loadFeed() }
        .refreshable { await loadFeed() }
    }

    private func loadFeed() async {
        do {
            let posts = try await client.getFeed()
            viewState = .loaded(posts)
        } catch {
            viewState = .error(error.localizedDescription)
        }
    }
}

For MV pattern rationale, app wiring, and lightweight client examples, see [references/architecture-patterns.md](references/architecture-patterns.md).

State Management

`@Observable` Ownership Rules

**Important:** Isolate UI-bound `@Observable` stores and view models on `@MainActor` when SwiftUI views own them, mutate them, or bind to their properties. Observation tracks changes; it does not make shared mutable state thread-safe. Domain models that do not touch UI state can use their own isolation strategy.

| Wrapper | When to Use | |---------|-------------| | `@State` | View owns the object or value. Creates and manages lifecycle. | | `let` | View receives an `@Observable` object. Read-only observation -- no wrapper needed. | | `@Bindable` | View receives an `@Observable` object and needs two-way bindings (`$property`). | | `@Environment(Type.self)` | Access shared `@Observable` object from environment. | | `@State` (value types) | View-local simple state: toggles, counters, text field values. Always `private`. | | `@Binding` | Two-way connection to parent's `@State` or `@Bindable` property. |

Ownership Pattern

// UI-bound @Observable store -- main-actor isolated
@MainActor
@Observable final class ItemStore {
    var title = ""