home / skills / petekp / claude-code-setup / macos-app-design

macos-app-design skill

safe

This skill helps you design native macOS apps with SwiftUI or AppKit by following system conventions and Liquid Glass guidelines.

npx playbooks add skill petekp/claude-code-setup --skill macos-app-design

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

Files (3)

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 design and build native-feeling macOS apps using SwiftUI or AppKit, focusing on system conventions, accessibility, and multi-window behavior. It guides decisions around menu structure, keyboard shortcuts, Liquid Glass usage, sidebars, toolbars, icons, and how to make an app a “good Mac citizen.” Use it to validate UI choices and produce deliverables before implementation.

How this skill works

It inspects your app archetype, menu and command map, window model, and UI chrome decisions to surface deviations from macOS expectations. It flags risky customizations (glass on content, overridden shortcuts, misplaced Settings) and recommends system components, accessibility checks, and layout patterns. It also recommends implementation deliverables like state models, undo/redo, and keyboard-first flows.

When to use it

Early design phase to choose an app archetype and information architecture
Before implementing menus, keyboard shortcuts, or multi-window behavior
When deciding whether to use Liquid Glass for navigation or controls
To audit accessibility, VoiceOver, and Reduced Motion support
Prior to final UI polish to ensure the app feels like a good Mac citizen

Best practices

Prefer system components and native controls over bespoke UI unless justified
Keep menu layout standard (App/File/Edit/View/Window/Help) and expose primary commands with ⌘ shortcuts
Limit Liquid Glass to navigation/controls layers; avoid glass over content
Group toolbar actions by function; demote secondary actions to a “more” menu
Plan multi-window behavior, fullscreen support, and fluid resizing from the start
Deliver a command map, state/data model, and accessibility plan before coding

Example use cases

Designing a library + editor app with a sidebar and detail editor
Auditing an existing app that feels off on macOS (missing shortcuts, odd menus)
Choosing when to apply Tahoe/Sequoia visual styles or Liquid Glass to toolbars
Defining keyboard-first workflows and undo/redo semantics for a document app
Preparing deliverables for engineers: navigation structure, command map, and accessibility checklist

FAQ

What are the two most important rules for macOS apps?

Prefer system components and conventions, and always justify any customization of bars, backgrounds, borders, or control chrome.

When is Liquid Glass appropriate?

Use it for navigation and controls layers (toolbars and sidebars). Avoid applying it to document or content layers and never stack glass elements.