playbooks

home / skills / petekp / agent-skills / macos-app-design

macos-app-design skill

/skills/macos-app-design

This skill helps you design macOS apps that feel native and citizen-friendly by aligning with system conventions and Liquid Glass rules.

npx playbooks add skill petekp/agent-skills --skill macos-app-design

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
3.1 KB
---
name: macos-app-design
description: 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."
---

# macOS App Design & Development

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

| 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

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](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 |

Overview

This skill helps designers and developers build native-feeling macOS apps with SwiftUI or AppKit, focusing on system conventions, keyboard-first workflows, and macOS visual language like Liquid Glass. It prioritizes making apps behave like a “good Mac citizen”: fast, accessible, multi-window aware, and consistent with platform expectations. Use it to audit or plan menu structure, shortcuts, sidebars, toolbars, icons, and overall app archetype.

How this skill works

The skill inspects your app’s UI and interaction surface against macOS conventions: menu bar layout, keyboard shortcuts, window behavior, sidebar/navigation patterns, toolbar grouping, and where Liquid Glass is applied. It flags deviations from platform standards, recommends keyboard mappings and menu placement, and produces concrete deliverables to resolve gaps (archetype, information architecture, command map, state model, accessibility plan).

When to use it

  • Early design phase to choose an app archetype (document, library+editor, utility, menu-bar, pro tool)
  • Before implementation to define menu structure and keyboard command map
  • While designing sidebars, toolbars, or Liquid Glass usage to avoid misapplication
  • When auditing an existing macOS app for platform consistency and accessibility
  • Prior to release to confirm multi-window behavior, fullscreen support, and system shortcut compatibility

Best practices

  • Prefer built-in system components and conventions; custom chrome must be justified
  • Put Settings in the App menu and expose primary commands in the menu bar with standard ⌘ shortcuts
  • Make every primary command reachable by keyboard; do not override common system shortcuts (⌘C/⌘V/⌘Z)
  • Use Liquid Glass only for navigation/controls (toolbars, sidebars), never for main content layers
  • Group toolbar items by function and demote secondary actions into a “more” menu or popover
  • Plan accessibility and state early: VoiceOver labels, full keyboard navigation, Reduced Motion, undo/redo, and persistence

Example use cases

  • Designing a mail or notes app that uses a sidebar + editor layout and multiple windows
  • Converting a single-window utility into a multi-window, document-based workflow
  • Auditing an app that misuses translucent chrome or places settings outside the App menu
  • Defining a keyboard-first command map for a pro tool with dense shortcuts
  • Planning iconography and SF Symbols usage for consistent macOS look-and-feel

FAQ

What is Liquid Glass allowed for?

Use Liquid Glass for navigation and controls (sidebars, toolbars, bars). Avoid applying it to content areas like documents, tables, and lists.

How should I handle keyboard shortcuts?

Expose every primary command via keyboard, follow macOS standard shortcuts, and never reassign common system shortcuts like ⌘C/⌘V/⌘Z.

When should I support multiple windows?

Support multiple windows whenever users work on multiple items or compare content; single-window is appropriate only for simple utilities or menu-bar apps.