kmshdev/claude-swift-toolkit/macos-app-design

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

1. Prefer system components and conventions over bespoke UI—fastest path to "feels right on Mac"
2. If you customize bars, backgrounds, borders, or control chrome: stop and justify it

Quick Reference: Mac Citizen Checklist

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

1. App archetype identified
2. Information architecture (sidebar structure, navigation, window model)
3. Command map (menus + keyboard shortcuts for every major feature)
4. State + data model (persistence, undo/redo, concurrency)
5. 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