macos-swiftui_skill

Overview

This skill provides practical guidance for building macOS 14+ (Sonoma) apps with SwiftUI and modern Swift patterns. It covers window management, NavigationSplitView, menus, Settings, document-based apps, toolbars, and macOS-specific integrations. Use it to design multi-window interfaces, integrate menu commands, and follow platform conventions for polished macOS apps.

How this skill works

The skill explains scene types (WindowGroup, Window, DocumentGroup, MenuBarExtra, Settings) and shows how to open and manage windows programmatically. It documents NavigationSplitView and NavigationStack patterns for sidebar/content/detail layouts, toolbar and menu command setup (including FocusedValue usage), and FileDocument for document-based apps. It also covers AppKit interoperability points like NSViewRepresentable and system integrations such as notifications and menu bar extras.

When to use it

• Starting a new macOS app targeting macOS 14+ using SwiftUI
• Implementing a sidebar + content + detail layout with NavigationSplitView
• Building a multi-window or document-based app with WindowGroup or DocumentGroup
• Adding native macOS menus, keyboard shortcuts, and focused scene state
• Creating a Settings (Preferences) window with persisted @AppStorage values
• Integrating AppKit components or advanced pasteboard/drag-and-drop behavior

Best practices

• Set minimum deployment to macOS 14.0 and enable strict concurrency checks
• Give windows sensible default sizes and resizability to match content
• Use FocusedValue and focusedSceneValue for window-specific state and menu actions
• Persist preferences with @AppStorage and expose Settings as a dedicated scene
• Prefer SwiftData or structured models for state; mark ViewModels @MainActor
• Avoid force-unwrapping, check file read/write errors in document apps

Example use cases

• A three-column mail client using NavigationSplitView with balanced column widths
• A multi-document text editor built with FileDocument and DocumentGroup
• An inspector window opened via .openWindow(id:) from the main view
• A status bar helper implemented with MenuBarExtra and lightweight UI
• A table-driven file manager using Table, sortable columns, and drag/drop