LogWhispererAI/.opencode/skills/ui-ux-master/references/apple-macos.md

macOS Design Patterns

Complete guide to macOS-specific design patterns, windows, and interactions.

Table of Contents

1. Windows & Window Management
2. Navigation & Layout
3. Toolbars & Menus
4. Controls & Input
5. Keyboard & Mouse Interaction

---

1. Windows & Window Management

Window Types

Standard Window:

• Resizable
• Minimize, maximize, close buttons (traffic lights)
• Title bar with app name
• Optional toolbar

Utility Window:

• Smaller title bar
• Floats above standard windows
• For palettes, inspectors

Panel:

• No title bar decorations
• Typically attached to main window
• For transient UI (color picker, find panel)

Window Controls

Traffic Lights (left side):

• 🔴 Close: Closes window (not app, unless last window)
• 🟡 Minimize: Sends to Dock
• 🟢 Zoom: Toggles full screen or maximizes

Full Screen:

• Green button (hold for options)
• Hides menu bar and Dock
• Swipe between full screen apps

Title Bar Styles

Standard:

• Opaque title bar
• Clear separation from content

Unified:

• Toolbar and title bar merged
• Content extends to top

Transparent:

• Content visible through title bar
• For immersive experiences

---

2. Navigation & Layout

Sidebar

Use when: Multiple sections or categories

Characteristics:

• Leading edge of window
• List or outline of navigation items
• Collapsible with ⌘⌃S
• Icon + text or text-only items

Best Practices:

• Use SF Symbols for icons
• Highlight selected item
• Support keyboard navigation (↑↓)

Split View

Use when: Master-detail relationship

Types:

• 2-pane: Sidebar + content (Mail, Notes)
• 3-pane: Sidebar + list + detail (Mail)

Interaction:

• Resize divider (drag)
• Collapse/expand panes
• Persist user preferences

Tabs

Use when: Multiple documents or views in one window

Characteristics:

• Below title bar
• Draggable to reorder
• Drag out to create new window
• Close button on each tab

Keyboard:

• ⌘T: New tab
• ⌘W: Close tab
• ⌘⇧[ / ⌘⇧]: Previous/next tab

---

3. Toolbars & Menus

Toolbar

Use when: Primary actions for current context

Items:

• Buttons (icon, text, or both)
• Segmented controls (view switchers)
• Search fields
• Pop-up buttons (menus)

Customization:

• Right-click → Customize Toolbar
• User can add/remove/rearrange items

Best Practices:

• Use SF Symbols
• Show icon + text by default
• Group related actions

Menu Bar

Always present at top of screen

Standard Menus:

• App Menu: About, Preferences, Quit
• File: New, Open, Save, Print, Close
• Edit: Undo, Cut, Copy, Paste
• View: Show/Hide UI elements
• Window: Minimize, Zoom, Bring All to Front
• Help: App help and search

Keyboard Shortcuts:

• ⌘: Command (primary)
• ⌥: Option (alternative)
• ⌃: Control (context-specific)
• ⇧: Shift (modifier)

Context Menus

Trigger: Right-click or Control+click

Content:

• Relevant actions for clicked item
• Cut, copy, paste when applicable
• Open, rename, delete for files

---

4. Controls & Input

Buttons

Types:

• Push Button: Standard action (rounded rect)
• Default Button: Primary action (blue, ↩ activates)
• Bevel Button: Icon-only, toolbar style
• Help Button: Small (?) for contextual help

Sizes:

• Regular (System default)
• Small (compact UIs)
• Mini (very compact, avoid if possible)

Pop-Up Buttons

Use when: Selecting from a list (dropdown)

Styles:

• Standard (with arrows)
• Pull-down (menu style)

Items:

• Checkmark for selected item
• Dividers between groups
• Icons (optional)

Segmented Control

Use when: 2-5 mutually exclusive view modes

Styles:

• Automatic: Adapts to context
• Rounded: Modern, iOS-like
• Textured: Toolbar style (legacy)

Text Fields & Search

Text Field:

• Single-line input
• Optional placeholder
• Clear button (×)

Search Field:

• Magnifying glass icon
• Rounded appearance
• Recent searches menu
• Cancel button appears when typing

Sliders & Steppers

Slider:

• Continuous value selection
• Optional tick marks
• Label showing current value

Stepper:

• Increment/decrement numeric values
• • and – buttons
• Typically paired with text field

---

5. Keyboard & Mouse Interaction

Keyboard Shortcuts

Universal:

• ⌘N: New
• ⌘O: Open
• ⌘S: Save
• ⌘P: Print
• ⌘Z: Undo
• ⌘⇧Z: Redo
• ⌘C/X/V: Copy/Cut/Paste
• ⌘Q: Quit

Window Management:

• ⌘M: Minimize
• ⌘W: Close window/tab
• ⌘⌃F: Full screen
• ⌘`: Switch windows of app

Tab Navigation:

• ⇥ (Tab): Next field
• ⇧⇥: Previous field
• ⌘⇥: Switch apps
• ⌘⇧⇥: Switch apps (reverse)

Mouse & Trackpad

Mouse:

• Left click: Select
• Right click: Context menu
• Scroll wheel: Vertical scroll

Trackpad Gestures:

• Two-finger scroll: Vertical/horizontal scroll
• Two-finger tap: Right-click
• Pinch: Zoom
• Swipe (3 fingers): Navigate back/forward
• Swipe up (3 fingers): Mission Control
• Swipe up (4 fingers): App Exposé

Drag & Drop

System-wide:

• Files between Finder and apps
• Text between apps
• Images from web to desktop

In-app:

• Reorder lists
• Move items between views
• Copy/move with modifier keys (⌥ = copy)

---

macOS-Specific Features

Preferences

Standard window:

• ⌘, (Command-comma) shortcut
• Toolbar with icons for sections
• No OK/Cancel buttons (apply immediately)

Notifications

Notification Center:

• Right side of screen
• Banners (auto-dismiss) or Alerts (require action)
• Do Not Disturb mode

Quick Look

Preview without opening:

• Select file, press Space
• Arrow keys to navigate
• Markup tools (annotation)

Spotlight

⌘Space: Universal search

• Apps, documents, contacts, definitions
• Calculator, unit conversions
• Web search

Extensions

Share Extension:

• Share button in toolbar/menu
• Send to other apps or services

Finder Extension:

• Add items to Finder sidebar
• Custom actions in Finder

---

Layout Guidelines

Window Sizing

Minimum:

• 600×400pt for document windows
• 400×300pt for utility windows

Default:

• Reasonable size for content
• Remember user's last size

Maximum:

• No artificial limits
• Scale content appropriately

Margins & Spacing

Standard spacing:

• 20pt: Window edges to content
• 12pt: Between controls (standard)
• 8pt: Between controls (compact)
• 24pt: Between groups

Alignment

• Left-align labels and text
• Right-align numeric data
• Center only for single, prominent elements

---

Accessibility (macOS)

VoiceOver

• Full keyboard navigation
• Descriptive labels for all controls
• Announce state changes
• Logical focus order

Keyboard Access

• Full Keyboard Access: Enable in System Settings
• All controls accessible via Tab
• Space to activate buttons
• Arrow keys for lists

Reduce Motion

• Minimize animations
• Use crossfades instead of slides
• Respect NSWorkspace.shared.accessibilityDisplayShouldReduceMotion

Contrast

• Increase Contrast mode (System Settings)
• Test UI with Increased Contrast enabled
• Avoid low-contrast text

---

Design Checklist

✅ Window Management

• Resizable windows (with min/max sizes)
• Remembers window position and size
• Full screen support (if appropriate)

✅ Navigation

• Clear hierarchy (sidebar or tabs)
• Keyboard shortcuts for common actions
• Context menus for quick access

✅ Toolbars

• Customizable toolbar
• Relevant actions visible
• Icon + text labels

✅ Menu Bar

• Standard menus (File, Edit, View, Window, Help)
• Keyboard shortcuts documented
• Disabled items when not applicable

✅ Input

• Tab order logical
• Keyboard shortcuts intuitive
• Drag & drop supported

✅ Accessibility

• VoiceOver labels on all controls
• Full keyboard access
• Reduce Motion respected
• High contrast support

✅ macOS Integration

• Uses system font (SF Pro)
• Supports Light and Dark mode
• Respects system preferences
• Native look and feel

---

For component-specific details, see macos-components.md