iOS SwiftUI Expert Skill

Core Rules

1. Use @Observable (iOS 17+) over ObservableObject — fine-grained property tracking, better performance, simpler syntax.
2. Use @State to own @Observable instances, NOT @StateObject. @StateObject is the pre-iOS 17 pattern.
3. Use NavigationStack (not NavigationView) with value-based NavigationLink + .navigationDestination.
4. Never nest NavigationStack inside NavigationStack — causes double navigation bars and broken behavior.
5. Use LazyVStack/LazyHStack inside ScrollView for large collections. Use List for very large datasets (cell reuse + prefetching).
6. Keep `body` pure — no data processing, network calls, or side effects. Use .task modifier for async work.
7. Avoid `AnyView` — it destroys view identity and kills diffing performance. Use @ViewBuilder or Group instead.
8. Preserve view identity — use ternary operators (condition ? viewA : viewB), not if/else that changes the view type in ways that break animations.
9. Break large views into small subviews — SwiftUI re-evaluates body often; smaller views = smaller re-evaluation scope.
10. Use `.equatable()` on expensive views to skip unnecessary re-renders.

Decision Tables

State Management — What to Use When

Key insight: With @Observable, SwiftUI tracks which properties a view actually reads in body. With ObservableObject, ANY @Published change triggers ALL observing views to re-evaluate.

Layout — What Container to Use

Navigation — Which Pattern

Presentation — Sheets vs Alerts vs Popovers

Quick Patterns

Creating an @Observable Model (iOS 17+)

@Observable
class UserViewModel {
    var name = ""
    var email = ""
    var isLoading = false

    @ObservationIgnored  // not tracked
    var internalCache: [String: Any] = [:]

    func load() async {
        isLoading = true
        defer { isLoading = false }
        // fetch data...
    }
}

struct UserView: View {
    @State private var viewModel = UserViewModel()

    var body: some View {
        Form {
            TextField("Name", text: $viewModel.name)  // needs @Bindable or use @State
        }
        .task { await viewModel.load() }
    }
}

Note: To get $viewModel.name binding from @State, you can access it directly. If the model is passed as a parameter (not @State), wrap with @Bindable:

struct EditView: View {
    @Bindable var viewModel: UserViewModel

    var body: some View {
        TextField("Name", text: $viewModel.name)
    }
}

Navigation Stack with Programmatic Navigation

struct ContentView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            List(items) { item in
                NavigationLink(value: item) {
                    Text(item.title)
                }
            }
            .navigationDestination(for: Item.self) { item in
                DetailView(item: item, path: $path)
            }
            .navigationTitle("Items")
        }
    }
}

Custom ViewModifier

struct CardModifier: ViewModifier {
    func body(content: Content) -> some View {
        content
            .padding()
            .background(.background, in: .rect(cornerRadius: 12))
            .shadow(color: .black.opacity(0.1), radius: 4, y: 2)
    }
}

extension View {
    func cardStyle() -> some View {
        modifier(CardModifier())
    }
}

Async Data Loading

struct PostListView: View {
    @State private var posts: [Post] = []
    @State private var error: Error?

    var body: some View {
        List(posts) { post in
            Text(post.title)
        }
        .overlay {
            if posts.isEmpty && error == nil {
                ProgressView()
            }
            if let error {
                ContentUnavailableView("Error", systemImage: "exclamationmark.triangle",
                    description: Text(error.localizedDescription))
            }
        }
        .task {
            do {
                posts = try await api.fetchPosts()
            } catch {
                self.error = error
            }
        }
    }
}

Reference File Routing

Use this table to decide which reference file to read for a given task:

Common Anti-Patterns to Avoid

1. Using `@StateObject` with `@Observable` — @StateObject is for ObservableObject only. Use @State with @Observable.

1. Using `@ObservedObject` with `@Observable` — just pass the object directly; observation is automatic.

1. Nesting `NavigationStack` inside another NavigationStack — causes double nav bars and broken navigation.

1. Using `NavigationView` — deprecated since iOS 16. Use NavigationStack or NavigationSplitView.

1. Heavy work in `body` — body is called frequently. Move computation to .task, .onAppear, or the model.

1. Using `AnyView` — type-erases the view, preventing SwiftUI from diffing efficiently. Use @ViewBuilder or Group.

1. Using `GeometryReader` for simple layouts — it proposes all available space to its child. Use proper stack alignment, .frame(), or containerRelativeFrame instead.

1. Forgetting `.id()` on ForEach items — causes incorrect diffing, wrong animations, and state bugs. Always use Identifiable or explicit id:.

1. Using `.onAppear` for async work — use .task instead; it auto-cancels when the view disappears.

1. Creating `@State` from init parameters — @State initializes once. If you need to react to parameter changes, use .onChange(of:) or derive state differently.

iOS Version Feature Matrix

Project Structure Convention

MyApp/
├── MyAppApp.swift          // @main App struct
├── Models/                 // Data models, @Observable classes
├── Views/
│   ├── Components/         // Reusable small views
│   ├── Screens/            // Full-screen views
│   └── Modifiers/          // Custom ViewModifiers
├── Services/               // Network, persistence, etc.
├── Extensions/             // View+, Color+, etc.
└── Resources/              // Assets, Localizable

Naming Conventions

• Views: noun or noun phrase (ProfileView, SettingsScreen, UserRow)
• ViewModels: <Feature>ViewModel with @Observable
• Modifiers: adjective or style name (CardModifier, PrimaryButtonStyle)
• Use some View return type, never concrete view types in public API