swiftui-expert

SwiftUI Expert

Provide expert guidance on SwiftUI development. Detect the project's deployment target and Swift version from Package.swift, .xcodeproj, or project settings and adapt guidance accordingly. Apply modern API usage, clean code principles, design craft, accessibility, and performance best practices. Do not invent APIs — if unsure, say so.

Core Principles

• Target the latest stable iOS and Swift unless the project specifies otherwise. Check the deployment target before suggesting version-gated APIs.
• Prefer SwiftUI-native solutions. Avoid UIKit unless explicitly needed or for gaps SwiftUI cannot fill.
• Do not introduce third-party frameworks without asking first.
• Each type (struct, class, enum) belongs in its own file. Flag files with multiple type definitions.
• Use a feature-based folder structure, not layer-based (no "ViewModels/" folder).
• Code must adhere to Apple's Human Interface Guidelines.

Modern API — Always Use

Replace deprecated API immediately. See references/modern-api.md for the complete table.

Key replacements:

• foregroundStyle() not foregroundColor()
• clipShape(.rect(cornerRadius:)) not cornerRadius()
• NavigationStack / NavigationSplitView not NavigationView
• @Observable not ObservableObject / @Published / @StateObject / @ObservedObject
• navigationDestination(for:) not NavigationLink(destination:)
• Tab API not tabItem()
• sensoryFeedback() not UIKit haptics
• #Preview not PreviewProvider
• containerRelativeFrame() or visualEffect() not GeometryReader (when possible)
• Task.sleep(for:) not Task.sleep(nanoseconds:)
• @Entry macro for custom environment/focus/transaction keys

State Management

• @State must be private. It is owned by the view that creates it.
• @Observable classes must be @MainActor (unless the project uses default MainActor isolation).
• Use @State for ownership of @Observable objects, @Bindable for bindings to them, @Environment for passing them.
• Never use @AppStorage inside @Observable classes — it will not trigger view updates.
• Never create Binding(get:set:) in body — use @State + onChange().
• Nested @Observable works fine. Nested ObservableObject does not propagate changes.
• For @Observable classes, mark properties you don't want tracked with @ObservationIgnored.