swiftui-ui-patterns

SwiftUI UI Patterns

Quick Start

Existing Project

1. Identify the feature and primary interaction model (list, detail, editor, settings, tabbed)
2. Find nearby examples in the repo with rg "TabView\(" or similar
3. Apply local conventions: prefer SwiftUI-native state, keep state local
4. Build with small, focused subviews and SwiftUI-native data flow

New Project Scaffolding

1. Wire TabView + NavigationStack + sheets
2. Add minimal AppTab enum and RouterPath
3. Expand route and sheet enums as new screens are added

General Rules

• Use modern SwiftUI state (@State, @Binding, @Observable, @Environment)
• Avoid unnecessary view models - prefer MV (Model-View) over MVVM
• Prefer composition; keep views small and focused
• Use async/await with .task and explicit loading/error states
• Follow the project's formatter and style guide

Sheets Best Practices

• Prefer .sheet(item:) over .sheet(isPresented:) when state represents a selected model
• Avoid if let inside a sheet body
• Sheets should own their actions and call dismiss() internally

Workflow for a New SwiftUI View

1. Define the view's state and its ownership location
2. Identify dependencies to inject via @Environment
3. Sketch the view hierarchy and extract repeated parts into subviews
4. Implement async loading with .task and explicit state enum if needed
5. Add accessibility labels or identifiers for interactive UI
6. Validate with a build and update usage callsites if needed

MV Pattern (Preferred over MVVM)

SwiftUI views should be lightweight state expressions. Avoid ViewModels unless truly necessary.

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

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

    @State private var viewState: ViewState = .loading

    var body: some View {
        NavigationStack {
            List {
                switch viewState {
                case .loading:
                    ProgressView("Loading...")
                case .error(let message):
                    ErrorView(message: message, retry: { await loadFeed() })
                case .loaded(let posts):
                    ForEach(posts) { post in
                        PostRow(post: post)
                    }
                }
            }
            .task { await loadFeed() }
        }
    }

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