macos-swiftui-architect

macOS SwiftUI Architect

Use for macOS SwiftUI scene/component choices. Use macos-runtime-debugger for build/run, macos-view-architect for large-file extraction, and macos-appkit-bridge for AppKit-only behavior.

Start

• Existing project: read nearest scene/root view, identify interaction model, then open the relevant file from references/components-index.md.
• New app: choose scene model first: WindowGroup, Window, Settings, MenuBarExtra, or DocumentGroup.
• For menu-bar apps that should also show normal windows, use @NSApplicationDelegateAdaptor, .regular activation policy, and activate on launch.
• Use WindowGroup(..., id:) for a primary launched window; Window(...) for auxiliary/on-demand singleton windows.
• Decide state ownership before writing views: app-wide, scene/window scoped, or local.

Desktop Rules

• Design for pointer, keyboard, menus, multiple windows, toolbars, sidebars, inspectors, context menus, and search.
• Keep scenes explicit; do not hide settings, utility windows, or menu-bar flows inside one giant ContentView.
• Prefer system colors/materials and semantic foreground styles; avoid hardcoded white roots and opaque custom sidebars unless requested.
• Use @SceneStorage for per-window ephemeral state and @AppStorage for preferences.
• Prefer stable sidebar selection and NavigationSplitView over iOS-style push navigation when persistent structure helps.
• Keep primary actions available through UI chrome and keyboard/menu paths.
• Use SwiftUI-native APIs first; switch to macos-appkit-bridge for responder chain, panels, low-level windows, or text system control.

Sidebar Pattern

Native source-list rows: one leading icon, one title, and optional secondary detail line. Put dense metadata/cards in detail or inspector panes, not every sidebar row.

List(selection: $selection) {
  ForEach(items) { item in
    HStack(spacing: 10) {
      Image(systemName: item.systemImage).frame(width: 16).foregroundStyle(.secondary)
      VStack(alignment: .leading, spacing: 2) {
        Text(item.title).lineLimit(1)
        if let detail = item.detail {
          Text(detail).font(.caption).foregroundStyle(.secondary).lineLimit(1)
        }
      }
    }
    .tag(item.id)
  }
}
.listStyle(.sidebar)

Let NavigationSplitView sidebars use native materials. Apply custom surfaces only to detail cards or inspector sections.

State Ownership

Scenario	Pattern
Local control state	@State
Child mutates parent value	@Binding
Root-owned @Observable	@State
Injected observable/service	property or @Environment(Type.self)
Window selection/expansion	@SceneStorage when practical
Durable preference	@AppStorage
Legacy observable	@StateObject owner, @ObservedObject injected

Avoid

One app-sized ContentView; touch-first flows without desktop affordances; actions only behind gestures; menu bar labels over 30 characters; settings as a main-window destination; card sidebars inside .sidebar lists unless requested; opaque split-pane backgrounds by default; AppKit bridges before SwiftUI scenes/commands/windows have been tried.

New Scene

Pick scene type/state ownership, place actions in content/toolbar/commands/inspector/settings, choose layout, split files by responsibility, add keyboard/menu/toolbar exposure, then build/run and check multiwindow behavior, settings entry points, and selection stability.

References

• references/components-index.md
• references/windowing.md
• references/settings.md
• references/commands-menus.md
• references/split-inspectors.md
• references/menu-bar-extra.md