/macos-programmer

name: macos-programmer
description: macOS-specific development patterns, platform APIs, and decision frameworks. Use when developing Mac apps, macOS applications, Cocoa/AppKit code, or making SwiftUI vs AppKit decisions. Covers NSWindow management, NSDocument architecture, sandboxing, code signing, notarization, and macOS UI patterns. Applies to Mac Catalyst considerations.

macOS Programming

<skill_scope skill="macos-programmer"> **Related skills:**

• `swift-programmer` — Swift language fundamentals and Swift 6 concurrency
• `software-engineer` — General software engineering principles and system architecture
• `test-driven-development` — Testing philosophy and practices

This skill covers macOS-specific development patterns, platform APIs, and decision frameworks. It applies when developing Mac apps, working with Cocoa/AppKit code, or making SwiftUI vs AppKit decisions. </skill_scope>

Core Philosophy

<core_philosophy> **Hybrid by default.** Production Mac apps commonly combine SwiftUI and AppKit: SwiftUI for most view content, AppKit where the platform's window, text, and event systems are exposed only there. Where the line falls varies by app; the case studies in `<swiftui_vs_appkit_decision>` show teams landing at different points, and each macOS release moves some formerly AppKit-only capability into SwiftUI (see `<recent_changes>`). Treat AppKit fallback as expected work rather than a failure of SwiftUI, and re-check the boundary when the deployment target moves.

**Platform Identity:** macOS is not iOS with a bigger screen. Multiple windows, menu bars, keyboard navigation, document-based architecture, and precise window management are first-class citizens. Respect macOS conventions; don't port iOS patterns blindly. </core_philosophy>

SwiftUI vs AppKit: The Critical Decision Framework

<swiftui_vs_appkit_decision> **The Ground Truth from Production Apps:**

SwiftUI maturity differs between iOS and macOS. Two 2023 accounts from Mac apps in development show the shape of the gap. Ghostty (then in private beta) rewrote its SwiftUI app and window lifecycle management in AppKit (+802/-239 lines) when non-native fullscreen, which requires subclassing `NSWindow`, proved impossible in pure SwiftUI; its views stayed SwiftUI.[^ghostty-devlog] Multi.app moved to SwiftUI but still needed "some access to NSEvents, text input, and tweaking the first responder that just aren't possible with pure SwiftUI," and wrote that SwiftUI bugs on older macOS left them "approaching the cusp of dropping support entirely" for those versions.[^multi-swiftui] Both are dated; re-read the boundary against the current release before applying them.

**Use SwiftUI When:**

• New apps targeting macOS 14+, simple-to-medium complexity
• Standard UI elements suffice (lists, forms, navigation)
• Cross-platform iOS/macOS with acceptable compromises
• Rapid prototyping where bugs are acceptable
• Team willing to bridge to AppKit with `NSViewRepresentable` where a control or behavior isn't available in SwiftUI
• Can require a recent macOS; each release fixes SwiftUI-on-Mac issues, so older deployment targets carry more workarounds

**Use AppKit When:**

• Complex text editing (code editors, word processors, NSTextView-dependent workflows)
• Large datasets where profiling on a Release build shows SwiftUI `List` falling behind `NSTableView`; measure on the current OS, since a macOS 26 change to `NavigationLink` "improves performance of many `NavigationLink`s in lazy containers like `List`"[^macos26-notes]
• Custom window management (non-standard fullscreen, window subclassing, utility panels)
• UI that must idle at near-zero CPU (verify with Instruments rather than assuming either framework)
• Behavior that has been stable in AppKit across the OS versions you support, where the SwiftUI equivalent has changed release to release (check release notes for the specific control)
• Professional tools (IDEs, DAWs, design apps, terminals) whose text, window, or event needs exceed SwiftUI's surface

**The Hybrid Shape (Common in Production):**

Ghostty's arrangement after its rewrite: AppKit owns the app and window lifecycle and SwiftUI supplies the views.[^ghostty-devlog] The bridging mechanisms are `NSHostingController` (SwiftUI inside AppKit) and `NSViewRepresentable` (AppKit inside SwiftUI).

<swiftui_limitations> **SwiftUI Limitations on macOS (as of macOS 26; re-check each release):**

• Window subclassing is unavailable in pure SwiftUI; non-native fullscreen and similar behaviors need AppKit[^ghostty-devlog]
• Direct access to `NSEvent`, first-responder manipulation, and some text-input behavior is AppKit-only[^multi-swiftui]
• The menu bar cannot be customized to the degree AppKit allows
• `List` performance with large data sets can lag `NSTableView`; the gap is workload-dependent and narrowed in macOS 26, so measure rather than assume
• Memory growth relative to iOS for similar apps has been reported by developers; treat it as something to profile, not a settled property

Capabilities that have moved into SwiftUI recently, such as styled text editing with `AttributedString` and Find Bar control in `TextEditor` on macOS 26, are listed in `<recent_changes>`. </swiftui_limitations>

**Decision Pattern:**

Production Mac App
├── AppKit: NSApplication, NSWindow, NSWindowController, NSDocument
├── SwiftUI: View content where appropriate
└── Bridge: NSHostingController, NSViewRepresentable

</swiftui_vs_appkit_decision>

Platform Differences from iOS (Critical for iOS Developers)

<platform_differences>

**Coordinate Systems:**

• iOS origin: top-left, Y increases downward
• macOS (unflipped `NSView`) origin: bottom-left, Y increases upward
• Override `isFlipped` to return `true` for iOS-style coordinates
• Drawing into a flipped context without compensating can draw images upside down; check the drawing API's handling of flipped contexts

**Layer Backing:**

• iOS views are layer-backed by default
• macOS views