Swift and SwiftUI

The code is right when it compiles with zero warnings in Swift 6 language mode and the app does what the story says. For how it should look, call the Skill tool with mac-design. For copyable view code, read ../../design/mac-design/patterns.md.

Concurrency

The template sets main-actor default isolation: every type and function runs on the main actor unless you say otherwise. UI code needs no annotations.

• Data that crosses actors is Sendable: structs and enums of Sendable values, or final class with only let properties.
• MainActor.assumeIsolated { } inside a callback you know runs on the main thread (a main run loop Timer, a main queue notification).
• Task { } inherits the actor. Task.detached only when it must not.
• Fix a concurrency error at its type, not with @unchecked Sendable or nonisolated(unsafe). Those two are a last resort, with a comment why.
• Runtime trap the compiler misses. A closure created inside a @MainActor type and passed to an API without a @Sendable closure parameter (DispatchSource.setEventHandler, DispatchWorkItem, addPeriodicTimeObserver, CoreAudio listener blocks) inherits the main actor. When it runs on a background queue, Swift 6 crashes the app. Write it as { @Sendable in ... }, and run every background path once after any concurrency change.

State

• @Observable classes for models. @State in the view that owns one, @Bindable to bind to its properties, .environment(model) to share it.
• @ObservationIgnored on caches, timers, and handles, so they never trigger a redraw.
• @State for view-local values. @AppStorage for small preferences. Keychain for secrets.
• ForEach(items) over values, never ForEach($items) for data the user can delete: a row can read an index that no longer exists and crash. Get a binding by looking the item up by id.

SwiftData

• @Model classes, .modelContainer on the scene, @Query in views, @Environment(\.modelContext) to insert and delete.
• Every new property has a default value, so existing stores still open.
• Store at ~/Library/Application Support/<AppName>/. Allow an override (APP_STORE) so tests never touch the real data.
• Give every model its own uid: UUID. persistentModelID changes on the first save, so it breaks selection and lookups.
• Undo: register the reverse of each action on the window's undo manager. SwiftData's automatic undo is not reliable. Code in ../../design/mac-design/patterns.md (Undo with SwiftData).
• Need SQL, a CLI, or several processes on one file? Use SQLite with WAL through a small library target instead.

Menu commands

SwiftUI Commands do not observe @Observable models, so a title or a .disabled(...) that reads the model goes stale. In testing, neither @FocusedValue (from .focusedSceneValue) nor an @ObservedObject inside the commands updated reliably: the menu stayed disabled with a row selected. What works: mirror the selection into a small ObservableObject, observe it in the App, and pass the values into the commands. The App's body then rebuilds the menus when they change.

@MainActor final class MenuState: ObservableObject {
    static let shared = MenuState()
    @Published private(set) var selection: Set<UUID> = []
    func update(_ s: Set<UUID>) { if selection != s { selection = s } }
}
// AppModel: var selection: Set<UUID> = [] { didSet { MenuState.shared.update(selection) } }

struct MyApp: App {
    @ObservedObject private var menu = MenuState.shared
    var body: some Scene {
        Window("App", id: "main") { ContentView() }
            .commands { AppCommands(model: model, selectedIDs: menu.selection) }
    }
}

Disable items with .disabled(selectedIDs.isEmpty) and resolve the target again when the item fires. Never ship items that stay enabled and do nothing. Check the menu from outside the app (test-mac-app skill, "Menu check").

A menu shortcut also fires while a text field has focus. Never use Delete, Command-Delete, arrows, or Return as menu shortcuts. Handle them on the list with .onDeleteCommand and .onKeyPress.

Names Swift already uses

Never name a type Task, View, Color, Image, Text, Section, Label, Menu, Group, or Settings. Task breaks every Task { }. Use Todo, TaskItem, NoteSection.

AppKit bridges

SwiftUI covers windows, lists, and forms. AppKit is still the answer for:

• Floating panels that do not steal focus: NSPanel with .nonactivatingPanel hosting a SwiftUI view (NSHostingView, with sizingOptions = [] for a fixed frame).
• Text views with custom behavior: NSViewRepresentable around NSTextView.
• Status items with custom click handling: NSStatusItem.
• Key and mouse monitors: NSEvent.addLocalMonitorForEvents. Remove the monitor when the view goes away.

For system hooks (hotkeys, Accessibility, screen capture), call the Skill tool with os-integrations.

Compiler errors

Fix the first error first. Later errors often come from it.

Swift 6 errors

Moving an existing Swift 5 app? Read ../../ship/build-and-verify/existing-app.md first: expect several build rounds, then hunt the runtime trap above.

Done when the app builds with zero warnings in Swift 6 language mode and the story's acceptance checks pass.