swift-conventions

Swift Conventions

Platform Requirements

• Swift 6 language version
• iOS 26+ deployment target
• SwiftUI-first architecture. UIKit is allowed only when no viable SwiftUI equivalent exists for a required feature.
• No Storyboards or XIBs

Allowed Frameworks

Only import from this list:

• SwiftUI
• Foundation
• SwiftData
• Observation
• OSLog (for logging)
• UIKit (only for required bridges or APIs without a SwiftUI equivalent)
• PhotosUI (only when the app requires photo picking)
• AVFoundation (only when the app requires audio/video)
• MapKit (only when the app requires maps)
• CoreLocation (only when the app requires location)

API Preferences

Use modern APIs — avoid deprecated alternatives:

Use This	Not This
foregroundStyle()	foregroundColor()
clipShape(.rect(cornerRadius:))	.cornerRadius()
@Observable	ObservableObject
@State with @Observable	@StateObject
.onChange(of:) { new in }	.onChange(of:) { old, new in } (iOS 17+ form)
.task { await … }	.onAppear { Task { await … } } (use .task for async work)
.onAppear { }	(acceptable for synchronous setup like passing modelContext)
NavigationStack	NavigationView

Swift 6 Concurrency Safety

Swift 6 enables strict concurrency checking by default. All data races are compile-time errors.

Sendable Conformance

• All types that cross isolation boundaries MUST conform to Sendable.
• Value types (structs, enums) with only Sendable stored properties are implicitly Sendable.
• Reference types (classes) must be final and have only immutable (let) Sendable stored properties, OR be marked @unchecked Sendable with manual thread safety (mutex/lock).
• Closures that cross isolation boundaries must be @Sendable — they cannot capture mutable local state.

@MainActor Isolation

• ViewModels that update @Published or @Observable state MUST be annotated @MainActor.
• Services that read/write UI-bound state MUST be @MainActor.
• SwiftUI Views are implicitly @MainActor, so @State var vm: SomeViewModel works if SomeViewModel is @MainActor.
• Use @MainActor on the class/actor declaration, not on individual methods — partial isolation causes confusing errors.