| name | macos-ui |
| description | Use when building AppKit/SwiftUI apps for Mac, or when /ibr:build preamble returns platform=macOS. Covers windows, toolbars, menu bar, materials, Liquid Glass, notarization, distribution. |
| version | 0.1.0 |
| user-invocable | false |
macOS UI
HIG-derived rules for Mac apps. Research context: docs/research/2026-04-13-mobile-ui-best-practices.md.
Windows
- Full-size content view is the modern default — content extends under the translucent titlebar. Use materials so toolbar vibrancy works
- Windows resizable unless content truly can't reflow
- Persist size + position across launches
- Support
NSWindow tabbing (⌘T) when the app is document-based or browsable
Toolbars, sidebars, inspectors
- Sidebar (source list):
.sidebar material, translucent with vibrancy. Shows hierarchy / top-level areas
- Toolbar: primary actions + search for current window; respect user customization
- Inspector: right-side contextual details panel; toggleable
Menus
Menu bar is first-class. Every command the user can invoke should be reachable from the menu bar — power users expect it.
Sacred shortcuts (never rebind):
- ⌘N / ⌘O / ⌘S / ⌘W / ⌘Q
- ⌘Z / ⇧⌘Z — undo/redo
- ⌘X / ⌘C / ⌘V — cut/copy/paste
- ⌘F — find
- ⌘, — preferences/settings
- ⌘? — help
- Control-⌘-F — full screen
Context menus supplement, never replace, menu bar items.
Keyboard-first
- Every interactive element tab-reachable
- Focus ring visible (WCAG 2.4.7)
- No mouse-only features
Pointer targets
Apple does not publish a single "macOS minimum target size" equivalent to iOS 44pt. Use WCAG 2.5.8 (24×24 px) as floor, 28–32 pt for standalone buttons. Hover states expected — cursor changes (I-beam, pointingHand, openHand).
Vibrancy + materials
NSVisualEffectView materials: sidebar, titlebar, menu, popover, HUD- Vibrancy pulls color through material — use vibrant label/fill/separator variants
- Four vibrancy levels: default (highest contrast) → quaternary (lowest)
- macOS 26 Tahoe Liquid Glass: translucent menu bar, Dock, Control Center. Desktop icons react to light/dark + tint. Verify exact SwiftUI modifier names against live Xcode docs before quoting
Colors
Same semantic-first rule as iOS — use NSColor.labelColor, NSColor.controlBackgroundColor, NSColor.separatorColor. In SwiftUI, Color(NSColor.labelColor) or Color.primary.
Typography
Default body = 13pt SF Pro on macOS (vs 17pt iOS). Match macOS system font scale — don't transplant iOS sizes.
Distribution
Path A — App Store
- Submit via Xcode Organizer → App Store Connect
- Full Apple review
- Sandbox required (entitlements declared in .entitlements)
- Universal binary: arm64 + x86_64 unless dropping Intel
Path B — Direct / Sparkle
- Developer ID signed + notarized — required since 2019 for Gatekeeper to pass silently
- Sparkle updaters: nested executables must also be Developer ID signed + timestamped, or notarization fails
- No sandbox required (but recommended)
Apple documentation — canonical entry points
HIG:
AppKit:
Distribution:
Keyboard reference:
Anti-patterns
- Hiding commands only in context menus (menu bar must have them)
- Rebinding sacred shortcuts
- Fixed-size windows for content that could reflow
- Hardcoded colors / fonts
- Transplanting iOS 17pt body directly — feels too large on Mac
- Shipping Intel-only binaries on Apple Silicon era
- Direct distribution without notarization → silent Gatekeeper fail for users
