macOS App Design & Development
Lifecycle Position
Phases 1-2 (Architecture → Design). After macos-development for system design. Next: load apple-liquid-glass-design for Liquid Glass adoption, then autonomous-ui-workflow for implementation.
Guide for designing and implementing native-feeling, "good Mac citizen" apps: fast, elegant, accessible, and deeply integrated with macOS workflows.
Two Rules That Beat Everything Else
- Prefer system components and conventions over bespoke UI—fastest path to "feels right on Mac"
- If you customize bars, backgrounds, borders, or control chrome: stop and justify it
Quick Reference: Mac Citizen Checklist
| Area |
Requirement |
| Menu Bar |
Standard layout (App/File/Edit/View/Window/Help), ⌘, for Settings |
| Keyboard |
Every primary command reachable via keyboard, standard shortcuts work |
| Windows |
Resize fluidly, support multiple windows, respect fullscreen/minimize |
| Sidebars |
Top-level navigation, scannable items, content extends behind |
| Toolbars |
Group by function/frequency, demote secondary to "more" menu |
| Text |
Use system text components, standard editing behaviors |
| Accessibility |
VoiceOver labels, full keyboard navigation, Reduced Motion support |
Liquid Glass Quick Rules
Do:
- Use for navigation/controls layer (toolbars, sidebars, bars)
- Let system components provide built-in behaviors
Don't:
- Apply to content layer (tables, lists, document content)
- Stack "glass on glass"
App Archetypes
Identify your app type first:
- Document-based: Files as primary units (open/save/duplicate)
- Library + editor: Sidebar lists items, detail in main area
- Utility: Single window, optional menu bar
- Menu-bar app: Lives in menu bar, minimal UI
- Pro tool: Dense, power-user workflows
Deliverables Before Building
- App archetype identified
- Information architecture (sidebar structure, navigation, window model)
- Command map (menus + keyboard shortcuts for every major feature)
- State + data model (persistence, undo/redo, concurrency)
- Accessibility plan (VoiceOver, keyboard, contrast, reduce motion)
Full Reference
For complete design system details, Icon Composer workflow, SF Symbols guidance, evaluation rubrics, and Definition of Done checklist:
See: references/macos-design-guide.md
Common Mistakes
| Mistake |
Fix |
| Missing menu bar commands |
Every feature in menus with keyboard shortcuts |
| Settings outside App menu |
Always ⌘, opening from App menu |
| Custom text components |
Use system text for Mac editing ecosystem |
| Toolbar overload |
Demote secondary actions, group by function |
| Glass on content |
Reserve Liquid Glass for navigation layer only |
| Breaking standard shortcuts |
Never override ⌘C, ⌘V, ⌘Z, etc. |
| Single-window only |
Support multiple windows when it benefits workflows |
1---2name: macos-app-design3description: Use when designing or building native macOS applications with SwiftUI or AppKit. Triggers on menu bar structure, keyboard shortcuts, multi-window behavior, Liquid Glass design system, macOS Tahoe/Sequoia, sidebar navigation, toolbar design, app icons, SF Symbols, or making an app feel like a "good Mac citizen."4---56# macOS App Design & Development78## Lifecycle Position910Phases 1-2 (Architecture → Design). After `macos-development` for system design. Next: load `apple-liquid-glass-design` for Liquid Glass adoption, then `autonomous-ui-workflow` for implementation.1112Guide for designing and implementing native-feeling, "good Mac citizen" apps: fast, elegant, accessible, and deeply integrated with macOS workflows.1314## Two Rules That Beat Everything Else15161. **Prefer system components and conventions** over bespoke UI—fastest path to "feels right on Mac"172. **If you customize bars, backgrounds, borders, or control chrome**: stop and justify it1819## Quick Reference: Mac Citizen Checklist2021| Area | Requirement |22|------|-------------|23| **Menu Bar** | Standard layout (App/File/Edit/View/Window/Help), ⌘, for Settings |24| **Keyboard** | Every primary command reachable via keyboard, standard shortcuts work |25| **Windows** | Resize fluidly, support multiple windows, respect fullscreen/minimize |26| **Sidebars** | Top-level navigation, scannable items, content extends behind |27| **Toolbars** | Group by function/frequency, demote secondary to "more" menu |28| **Text** | Use system text components, standard editing behaviors |29| **Accessibility** | VoiceOver labels, full keyboard navigation, Reduced Motion support |3031## Liquid Glass Quick Rules3233**Do:**34- Use for navigation/controls layer (toolbars, sidebars, bars)35- Let system components provide built-in behaviors3637**Don't:**38- Apply to content layer (tables, lists, document content)39- Stack "glass on glass"4041## App Archetypes4243Identify your app type first:44- **Document-based**: Files as primary units (open/save/duplicate)45- **Library + editor**: Sidebar lists items, detail in main area46- **Utility**: Single window, optional menu bar47- **Menu-bar app**: Lives in menu bar, minimal UI48- **Pro tool**: Dense, power-user workflows4950## Deliverables Before Building51521. **App archetype** identified532. **Information architecture** (sidebar structure, navigation, window model)543. **Command map** (menus + keyboard shortcuts for every major feature)554. **State + data model** (persistence, undo/redo, concurrency)565. **Accessibility plan** (VoiceOver, keyboard, contrast, reduce motion)5758## Full Reference5960For complete design system details, Icon Composer workflow, SF Symbols guidance, evaluation rubrics, and Definition of Done checklist:6162See: [references/macos-design-guide.md](references/macos-design-guide.md)6364## Common Mistakes6566| Mistake | Fix |67|---------|-----|68| Missing menu bar commands | Every feature in menus with keyboard shortcuts |69| Settings outside App menu | Always ⌘, opening from App menu |70| Custom text components | Use system text for Mac editing ecosystem |71| Toolbar overload | Demote secondary actions, group by function |72| Glass on content | Reserve Liquid Glass for navigation layer only |73| Breaking standard shortcuts | Never override ⌘C, ⌘V, ⌘Z, etc. |74| Single-window only | Support multiple windows when it benefits workflows |
kmshdev