Macos Design Guidelines

# macOS Design Guidelines — Agent Instructions

## Purpose

This skill provides Apple Human Interface Guidelines for macOS. Apply these rules when building, reviewing, or designing Mac apps using SwiftUI or AppKit.

## When to Apply

- Building any macOS application
- Reviewing Mac UI code or designs
- Implementing menu bars, toolbars, sidebars, or window management
- Adding keyboard shortcuts or pointer interactions
- Porting iOS apps to Mac via Catalyst or Designed for iPad
- Evaluating desktop app usability

## How to Use

1. Read `SKILL.md` for the full rule set with code examples
2. Read `rules/_sections.md` for the categorized quick-reference
3. Use the evaluation checklist in SKILL.md before shipping

## Priority

Rules marked CRITICAL must never be skipped. Rules marked HIGH should be followed unless there is a documented reason. Rules marked MEDIUM are strong recommendations.

## Rule Categories

| # | Category | Impact |
|---|----------|--------|
| 1 | Menu Bar | CRITICAL |
| 2 | Windows | CRITICAL |
| 3 | Toolbars | HIGH |
| 4 | Sidebars | HIGH |
| 5 | Keyboard | CRITICAL |
| 6 | Pointer and Mouse | HIGH |
| 7 | Notifications and Alerts | MEDIUM |
| 8 | System Integration | MEDIUM |
| 9 | Visual Design | HIGH |
| 10 | Popovers | MEDIUM |
| 11 | Accessibility | CRITICAL |

## Key Principles

- Mac users expect menu bars, keyboard shortcuts, and multi-window support
- Every destructive action needs Cmd+Z undo
- Toolbars and sidebars should be user-customizable
- Respect system appearance (Dark Mode, accent color, font size)
- Support drag and drop everywhere it makes sense
- Desktop apps are power-user tools — don't hide functionality behind discoverability walls

## Never Do

- Never ship without a menu bar
- Never use hamburger menus — use the menu bar or a sidebar
- Never place a tab bar at the bottom of the screen
- Never hardcode colors — use semantic system colors for Dark Mode compatibility
- Never build non-resizable main windows
- Never omit keyboard shortcuts for common actions
- Never block full keyboard navigation — no keyboard traps
- Never override traffic light buttons or window chrome
- Never use floating action buttons — use toolbar and menu bar actions
- Never ignore VoiceOver — every control needs an accessibility label


{
  "version": "1.0.0",
  "organization": "Platform Design Skills",
  "date": "February 2026",
  "abstract": "Apple Human Interface Guidelines for macOS apps. 60+ rules across 11 categories covering menu bars, window management, toolbars, keyboard-driven interaction, sidebars, popovers, accessibility, and desktop power-user expectations. Each rule includes SwiftUI/AppKit examples.",
  "references": [
    "https://developer.apple.com/design/human-interface-guidelines",
    "https://developer.apple.com/design/human-interface-guidelines/designing-for-macos",
    "https://developer.apple.com/documentation/swiftui",
    "https://developer.apple.com/documentation/appkit"
  ]
}


# macOS Design Guidelines — Section Index

Quick-reference for all 11 categories and 62 rules. See `../SKILL.md` for full details, code examples, and rationale.

---

## Section 1: Menu Bar [CRITICAL]

| Rule | Summary |
|------|---------|
| 1.1 | Provide standard menus: App, File, Edit, View, Window, Help |
| 1.2 | Keyboard shortcut for every menu item; follow standard conventions |
| 1.3 | Dynamic menu updates: disable unavailable items, update titles contextually |
| 1.4 | Right-click context menus on all interactive elements |
| 1.5 | App menu must contain About, Settings, Services, Hide, Quit |
| 1.6 | Keep common commands in stable menus with stable names and shortcuts |

**Key principle:** The menu bar is the primary command discovery surface and memory offload on Mac. Every action in the app must be reachable through the menu bar.

---

## Section 2: Windows [CRITICAL]

| Rule | Summary |
|------|---------|
| 2.1 | Resizable windows with sensible minimum sizes |
| 2.2 | Support native fullscreen and Split