macos-swiftui-patterns

SwiftUI Patterns

Quick Start

Choose a track based on your goal:

Existing project

• Identify the feature or scene and the primary interaction model: document, editor, sidebar-detail, utility window, settings, or menu bar extra.
• Read the nearest existing scene or root view before inventing a new desktop structure.
• Choose the relevant reference from references/components-index.md.
• If SwiftUI cannot express the required platform behavior cleanly, use the macos-appkit-interop skill rather than forcing a shaky workaround.

New app scaffolding

• Choose the scene model first: WindowGroup, Window, Settings, MenuBarExtra, or DocumentGroup.
• If the app combines a normal main window and a MenuBarExtra, use WindowGroup(..., id:) for the primary window when it should appear at launch. Treat Window(...) as a better fit for auxiliary/on-demand singleton windows; in menu-bar-heavy apps, a Window(...) scene may not present the main window automatically at launch.
• Before creating the scaffold, check whether the workspace is already inside a git repo with git rev-parse --is-inside-work-tree. If not, run git init at the project root so git-backed features are available from the start. Do not initialize a nested repo inside an existing parent checkout.
• For a new app scaffold, also create one project-local script/build_and_run.sh so the app has a single build/run entrypoint. Use the exact bootstrap contract from the macos-build-run-debug skill rather than inventing a second variant here.
• Decide which state is app-wide, scene-scoped, or window-scoped before writing views.
• Sketch file and module boundaries before writing the full UI. For any non-trivial app, create the folder structure first and split files by responsibility from the start.
• Use a single Swift file only for tiny throwaway examples or snippets: roughly under 50 lines, one screen, no persistence, no networking/process client, and no reusable models. Anything beyond that should be multi-file immediately.
• Use system-adaptive colors and materials by default (Color.primary, Color.secondary, semantic foreground styles, .regularMaterial, etc.) so the app follows Light/Dark mode automatically. Do not hardcode white or light backgrounds unless the user explicitly asks for a fixed theme, and do not reach for opaque windowBackgroundColor fills for root panes by default.
• Pick the references for the first feature surface you need: windowing, commands, split layouts, or settings.