Macos Design

macOS Native App Design Skill

Build interfaces that feel like they belong on the user's computer — not websites crammed into a window.

Core Philosophy

A native app is not a destination. It is a system tool that lives where the user needs it. Design every interaction around this principle: appear when needed, get out of the way immediately after.

Before You Code

Read these references based on what you're building:

• All macOS apps → Read references/layout-and-composition.md (required)
• Apps with keyboard shortcuts, panels, toasts, popovers → Read references/interaction-patterns.md
• Light/dark mode, color, typography → Read references/visual-design.md

Quick-Start Checklist

Use this as a pre-flight before writing any code:

1. Layout: Top bar for global actions, sidebar for navigation (skip if nav is minimal), center for content 2. Traffic lights: Integrate into the UI — top bar or sidebar, never floating awkwardly 3. Window drag zone: Top ~50px must be draggable, keep it uncluttered 4. Empty states: Show them. Progressive disclosure — only reveal UI when it's useful 5. Keyboard shortcuts: Every primary action needs one. Every shortcut needs visual feedback 6. Light + Dark mode: Design both. Do NOT directly invert colors (see visual-design reference) 7. Search: Always prominent and accessible. Consider floating search bar or command palette 8. Drag and drop: Content in AND out of the app. This is non-negotiable for native feel 9. Micro-animations: Every state change gets a transition. No interaction without feedback 10. Onboarding: Brief, modal-based, teaches shortcuts through doing (not reading)

Implementation Notes

When building as a web artifact (React/HTML):

• Simulate the macOS window chrome (title bar, traffic light dots, rounded corners)
• Use -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text" font stack
• Use backdrop-filter: blur() for native vibrancy/translucency effects
• Rounded corners: 10px for windows, 8px for cards, 6px for buttons, 4px for inputs
• Respect prefers-color-scheme media query for automatic light/dark switching
• Shadows should be subtle and layered, not a single heavy drop shadow

When building with Electron, Tauri, or native frameworks:

• Use system title bar integration where possible
• Respect system accent color and appearance settings
• Use native drag-and-drop APIs, not polyfills

Interaction Patterns Reference

Table of Contents

1. Keyboard Shortcuts 2. Visual Feedback & Micro-Animations 3. Search Patterns 4. Drag and Drop 5. Optimistic UI 6. Onboarding 7. Floating Action Bars

---

1. Keyboard Shortcuts

macOS is filled with keyboard shortcuts. They are a first-class interaction pattern, not an afterthought.

Rules:

• Every primary action MUST have a keyboard shortcut
• Show shortcut hints next to actions (e.g., button label + "⌘S" in lighter text)
• Use standard macOS conventions where applicable:
• ⌘N — New
• ⌘F — Find/Search
• ⌘W — Close window/tab
• ⌘, — Preferences/Settings
• ⌘⇧S — Save As / Quick Save
• ⌘Space — Spotlight-style search
• ⌘Tab — Switch (adapt to your context)
• Esc — Dismiss/Close/Cancel
• Enter/Return — Confirm/Submit

Shortcut hint rendering:

⌘  →  Command (looped square icon)
⇧  →  Shift
⌥  →  Option
⌃  →  Control

Display these in small rounded <kbd> style boxes:

.kbd {
  display: inline-flex;
  align-items: center;
  padding: 2px 6px;
  font-size: 11px;
  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
  background: rgba(128,128,128,0.12);
  border-radius: 4px;
  border: 0.5px solid rgba(128,128,128,0.2);
  color: inherit;
  opacity: 0.6;
  gap: 2px;
}

Shortcut cheat sheet: Provide a settings/preferences panel or a dedicated shortcut overlay (like Google Docs' ⌘/). Ironically triggered by another keyboard shortcut.

Critical: Keyboard shortcuts are powerful but easy to forget. Educate users through:

• Onboarding that teaches by doing (not reading)
• Persistent hints next to buttons
• A discoverable cheat sheet

---

2. Visual Feedback & Micro-Animations

Core principle: If you don't see a change, you assume something went wrong. Every interaction needs immediate visual feedback.

State changes that need animation:

• Panel sliding in/out (quicksave, preview, sidebar)
• Search bar expanding/collapsing
• Items appearing in a grid (stagger in)
• Toast notifications entering and exiting
• Hover states on cards and buttons
• Active/selected state changes
• Drag start/drag over/drop states

Animation guidelines:

/* Standard macOS-feel transitions */
--ease-out: cubic-bezier(0.25, 0.46, 0.45, 0.94);
--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);    /* slight overshoot */
--ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);

/* Durations */
--duration-fast: 150ms;     /* hover states, small changes */
--duration-normal: 250ms;   /* panels, expansions */
--duration-slow: 400ms;     /* page-level transitions */

/* Standard transition */
transition: all var(--duration-normal) var(--ease-out);

Slide-in panels:

.panel-enter {
  transform: translateX(100%);
  opacity: 0;
}
.panel-active {
  transform: translateX(0);
  opacity: 1;
  transition: transform 300ms cubic-bezier(0.25, 0.46, 0.45, 0.94),
              opacity 200ms ease;
}

Toast notifications:

• Enter: slide up + fade in from bottom-right (or bottom-center)
• Persist: 2-3 seconds
• Exit: slide right + fade out
• Should feel lightweight — small, rounded, with an icon + short text

Collapse/Expand (e.g., search bar):

.search-collapsed {
  width: 40px;
  border-radius: 20px;
  overflow: hidden;
}
.search-expanded {
  width: 320px;
  border-radius: 8px;
}
/* Transition between states */
.search-bar {
  transition: width 250ms var(--ease-out), border-radius 250ms var(--ease-out);
}

---

3. Search Patterns

Search is present in virtually every native macOS app. It must be prominent and accessible.

Option A: Floating Search Bar (Recommended for single-screen apps)

• Lives at the bottom or top of the content area
• Collapses to a small icon/pill when not in use
• Expands on click or keyboard shortcut (⌘F)
• Shows result count inline
• Has a clear button (✕) to reset
• Search query appears as a label/breadcrumb when active

[Browse]  ←  [🔍 "mobile app houses"  —  7 results  ✕]

Option B: Command Palette (Better for multi-screen apps)

• Triggered by ⌘K or ⌘Space
• Centered floating modal with backdrop blur
• Type to search across everything: pages, items, actions, settings
• Results grouped by category
• Keyboard-navigable (arrow keys + enter)
• Most powerful apps (Notion, Obsidian, Raycast, VS Code) use this

Option C: Inline Top Bar Search (Apple's standard)

• Persistent search field in the top bar, right-aligned
• Standard macOS search field appearance (rounded, magnifying glass icon, cancel button)
• Filters content in real-time as you type
• Used by: Finder, Music, Photos, App Store

Choosing which pattern:

• Single-screen utility with visual content → Floating Search Bar
• Complex app with many sections/actions → Command Palette
• Standard content browser → Inline Top Bar Search

Image-Based Search

If content is visual, consider AI-powered search that matches what's IN the image, not just titles/tags. Show results in a sidebar slideout with thumbnails of similar content. This is a differentiator that makes the app feel magical.

---

4. Drag and Drop

Apple has this down to a science. Drag and drop is non-negotiable for native feel.

Content IN:

• Drop zones should be obvious — highlight on dragover with a dashed border + accent color
• Accept from Finder, other apps, desktop
• Quick-save panels should accept drops directly
• Show a preview of what will be added before confirming

Content OUT:

• Any visual content should be draggable
• Dragging should create a ghost/preview that follows the cursor
• Drop into Figma, Finder, other apps, or desktop
• The drag image should be a scaled-down version of the content

Visual feedback during drag:

.drop-zone-active {
  border: 2px dashed var(--accent-color);
  background: rgba(var(--accent-rgb), 0.05);
  transition: all 150ms ease;
}

.dragging-item {
  opacity: 0.5;
  transform: scale(0.95);
  cursor: grabbing;
}

Implementation notes for web/React:

• Use onDragStart, onDragOver, onDragEnd, onDrop
• Set draggable="true" on content items
• Use e.dataTransfer.setData() and e.dataTransfer.setDragImage()
• For file drops: handle onDrop with e.dataTransfer.files

---

5. Optimistic UI

Process actions in the background and assume success. Show the result immediately.

Examples:

• Save an image → immediately show toast "Saved!" → process upload in background
• Delete an item → immediately remove from grid → delete from storage in background
• Move to folder → immediately update UI → sync in background

Why: Eliminates perceived latency. The app feels instant. Apple Mail does this — moving email to trash updates the UI before the server confirms deletion.

Implementation pattern:

1. User triggers action
2. Immediately update local state / UI
3. Show success feedback (toast, animation)
4. Process actual operation async
5. On failure: revert state + show error toast

Toast for optimistic actions:

• Short text: "Saved" / "Copied" / "Deleted"
• Small icon (checkmark)
• Auto-dismiss after 2s
• Slide away gracefully

---

6. Onboarding

Not standard for Apple's own apps, but critical for third-party Mac apps (Raycast does this excellently).

Principles:

• Keep it brief — a single modal, not a multi-step wizard
• Teach by DOING, not reading
• Focus on the 1-2 most important shortcuts/interactions
• The way to dismiss onboarding IS the shortcut (e.g., "Press ⌘⇧S to get started" → executing the shortcut closes the modal and opens the quicksave panel)
• Use micro-animations to demonstrate interactions
• Show, don't tell

Structure:

┌──────────────────────────────────┐
│                                  │
│     [Icon or animation]          │
│                                  │
│   Welcome to [App Name]          │
│                                  │
│   Save inspiration instantly     │
│   from anywhere.                 │
│                                  │
│   Press ⌘⇧S to start            │
│                                  │
│      [subtle pulse animation     │
│       on the shortcut hint]      │
│                                  │
└──────────────────────────────────┘

Shortcut cheat sheet (in settings):

• Grid of all shortcuts
• Grouped by category
• Triggered by its own shortcut (e.g., ⌘? or ⌘/)
• Can also live in a settings popover

---

7. Floating Action Bars

When viewing content in a detail/preview panel, provide a floating action bar for quick actions.

Design:

• Pill-shaped, horizontally laid out
• Floats at the bottom of the preview panel
• Slight backdrop blur + shadow
• Icons only (with tooltip on hover) or icon + short label
• Common actions: Copy, Share, Find Similar, Delete

CSS pattern:

.floating-action-bar {
  display: flex;
  gap: 4px;
  padding: 6px 10px;
  background: rgba(255,255,255,0.7);
  backdrop-filter: blur(20px);
  border-radius: 10px;
  box-shadow: 0 2px 12px rgba(0,0,0,0.1);
  border: 0.5px solid rgba(0,0,0,0.08);
}
/* Dark mode */
@media (prefers-color-scheme: dark) {
  .floating-action-bar {
    background: rgba(50,50,50,0.7);
    border: 0.5px solid rgba(255,255,255,0.1);
  }
}

Uses Apple's universal share button pattern (square with up-arrow) where appropriate. The share button should be present for any content that a user might want to export or send somewhere else.

Layout & Composition Reference

Table of Contents

1. The Apple Layout Formula 2. Top Bar Design 3. Sidebar Navigation 4. Content Area 5. Empty States & Progressive Disclosure 6. Window Chrome & Traffic Lights 7. Multi-Window & System Integration

---

1. The Apple Layout Formula

Nearly every Apple utility app follows the same structural pattern:

┌─────────────────────────────────────────────────┐
│  Traffic Lights  │      Top Bar (Global Actions) │  ← ~50px, draggable
├──────────────────┼──────────────────────────────┤
│                  │                               │
│    Sidebar       │       Main Content            │
│   (Navigation)   │       (User's Data)           │
│                  │                               │
│                  │                               │
│                  │                               │
├──────────────────┴──────────────────────────────┤
│              Bottom Bar (optional)               │
└─────────────────────────────────────────────────┘

Apps that use this: Finder, Notes, Reminders, Calendar, Settings, Music, Shortcuts, Mail.

Key insight: Apps are containers for the user's information. Unlike landing pages (pre-generated content that doesn't change), apps hold data the user adds and manipulates. This is why the layout is user-focused with content at center stage.

When to Skip the Sidebar

If navigation is minimal (just browsing + searching), drop the sidebar entirely. This gives extra room for content. The app becomes essentially a single-screen utility — which is how most of Apple's best tools work. They do one thing and do it well, so the UI stays hyperfocused.

---

2. Top Bar Design

The top bar serves global-level actions: search, view toggles, sort, new item.

Rules:

• Height: ~50px (this zone doubles as the window drag area)
• Keep it sparse — do NOT clutter with actions. Let it breathe
• Traffic lights can live here, flush left, treated as just another element
• Search is almost always present and prominent
• Use segmented controls for view switching (grid/list/etc.)

Example top bar structure:

[● ● ●]  [< Back]  Browse        [Search.............]  [+ New]  [⚙]

Common mistakes:

• Too many buttons crowding the drag zone
• Making the top bar feel like a toolbar instead of a title bar
• Forgetting that users need to grab this area to move the window

---

3. Sidebar Navigation

When your app needs a sidebar:

• Width: 200-260px, optionally resizable
• Background: slightly different shade than content (use vibrancy/blur in native apps)
• Sections grouped with small caps headers
• Active item: subtle highlight, not a loud color block
• Icons: SF Symbols style — thin, monoline, 16-20px
• Collapsible on smaller windows

When NOT to use a sidebar:

• App has fewer than 3 navigation destinations
• App is a single-purpose utility
• Content benefits more from full width

---

4. Content Area

The content area is the star. Everything else exists to support it.

Principles:

• Minimize UI chrome around content — the app is a container, not a frame
• Images and media should be large and breathable
• Grid layouts: consistent gaps (12-16px), responsive columns
• List layouts: generous row height, hover states, clear hierarchy
• Detail views: slide-out panels preferred over full page navigation (keeps context)

Grid layout guidelines:

Small window:   2 columns
Medium window:  3 columns
Large window:   4-5 columns
Gap:            12-16px
Padding:        16-24px from edges
Corner radius:  8px on cards

Detail / Preview pattern: Instead of navigating to a new page, slide out a panel from the right. This maintains context — the user can still see the grid behind the preview. Include a floating action bar in the preview for common actions (copy, delete, share, etc.).

---

5. Empty States & Progressive Disclosure

Empty state: When there's no content, show a clean, inviting placeholder.

• Centered in the content area
• Simple icon or illustration (not busy)
• One line of text explaining what goes here
• A clear CTA to get started
• All filters, toolbars, and secondary UI should be HIDDEN — they're useless without content

Progressive disclosure: Only show UI when the user needs it.

• Filters appear after content exists
• Metadata appears on hover or click, not by default
• Advanced options tucked behind a "..." menu or settings
• Search expands from a collapsed state when triggered

Ask yourself: What is the minimum UI needed to let the content shine?

---

6. Window Chrome & Traffic Lights

Traffic light buttons (close, minimize, maximize):

• Always positioned top-left
• Integrate them INTO the UI — they should feel like part of the sidebar or top bar, not a separate system element
• Standard spacing: 8px from top-left corner, 8px between dots
• Size: 12px diameter circles
• Colors: red (#FF5F57), yellow (#FEBC2E), green (#28C840)
• On hover: show ×, −, + icons inside
• When window is inactive: all three become gray (#CDCDCD)

Window properties:

• Corner radius: 10px (macOS standard)
• Shadow: layered — inner subtle shadow + outer soft spread
• Border: 0.5px solid with low opacity for definition
• Background: respect vibrancy when possible (slight transparency + blur)

Simulating in web/React:

.macos-window {
  border-radius: 10px;
  box-shadow:
    0 0 0 0.5px rgba(0,0,0,0.1),
    0 2px 8px rgba(0,0,0,0.08),
    0 8px 30px rgba(0,0,0,0.12);
  overflow: hidden;
}

---

7. Multi-Window & System Integration

Native macOS apps don't live only in their main window. Consider:

Popovers: Small floating panels for settings, quick actions, or confirmations. Appear near the triggering element with an arrow pointing to it.

Panels / Sheets: Slide down from the top of the window for modal-ish interactions that don't take over the whole screen.

Quick-access windows: Triggered by global keyboard shortcuts (like Spotlight via Cmd+Space). These float above everything, have no traffic lights, and are minimal — just the essential input + action. They should:

• Slide in quietly from the side or fade in from center
• Have backdrop blur (native vibrancy feel)
• Disappear on Escape or after completing the action
• Collapse into a toast notification on success

Toast notifications: After an action completes, show a small confirmation that slides away automatically. This is optimistic UI — assume success, process in background.

System tray / Menu bar: Some apps live primarily in the menu bar (like Paste, Bartender). Consider if your app benefits from always-available access without being a full window.

Share sheet: Apple's universal share button (square with up-arrow). Include it for any content that might leave your app.

Visual Design Reference

Table of Contents

1. Light & Dark Mode 2. Color System 3. Typography 4. Blur, Vibrancy & Translucency 5. Shadows & Depth 6. Iconography 7. Spacing & Sizing

---

1. Light & Dark Mode

Critical rule: Do NOT directly invert colors between modes.

Direct inversion causes problems because dark mode requires colors with MORE differentiation between them. When you directly invert a dark palette to light, the contrast is too high and harsh. When you invert light to dark, everything looks muddy.

Design each mode independently:

Light mode:

• Backgrounds should be close together (white, off-white, very light gray)
• Colors can be more collapsed / similar — the ambient light provides differentiation
• Text: near-black (#1D1D1F) on white (#FFFFFF) or off-white (#F5F5F7)

Dark mode:

• Backgrounds need more separation between levels (e.g., #1C1C1E, #2C2C2E, #3A3A3C)
• Colors should be more spread out and vibrant — compensating for less ambient light
• Text: off-white (#F5F5F7) on dark (#1C1C1E)
• Avoid pure black (#000000) backgrounds — Apple uses dark grays

The modes should feel different but consistent. Same layout, same structure, same brand — but the palette is adjusted, not mirrored.

CSS Variables Pattern

:root {
  /* Light mode (default) */
  --bg-primary: #FFFFFF;
  --bg-secondary: #F5F5F7;
  --bg-tertiary: #E8E8ED;
  --bg-elevated: #FFFFFF;

  --text-primary: #1D1D1F;
  --text-secondary: #6E6E73;
  --text-tertiary: #AEAEB2;

  --border: rgba(0, 0, 0, 0.08);
  --border-strong: rgba(0, 0, 0, 0.15);

  --accent: #007AFF;       /* System blue */
  --accent-hover: #0066D6;

  --surface-hover: rgba(0, 0, 0, 0.04);
  --surface-active: rgba(0, 0, 0, 0.08);

  --shadow-sm: 0 1px 3px rgba(0,0,0,0.06);
  --shadow-md: 0 4px 12px rgba(0,0,0,0.08);
  --shadow-lg: 0 8px 30px rgba(0,0,0,0.12);
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg-primary: #1C1C1E;
    --bg-secondary: #2C2C2E;
    --bg-tertiary: #3A3A3C;
    --bg-elevated: #2C2C2E;

    --text-primary: #F5F5F7;
    --text-secondary: #98989D;
    --text-tertiary: #636366;

    --border: rgba(255, 255, 255, 0.08);
    --border-strong: rgba(255, 255, 255, 0.15);

    --accent: #0A84FF;       /* Slightly brighter blue for dark */
    --accent-hover: #409CFF;

    --surface-hover: rgba(255, 255, 255, 0.06);
    --surface-active: rgba(255, 255, 255, 0.1);

    --shadow-sm: 0 1px 3px rgba(0,0,0,0.2);
    --shadow-md: 0 4px 12px rgba(0,0,0,0.3);
    --shadow-lg: 0 8px 30px rgba(0,0,0,0.4);
  }
}

Apple's system accent colors (use as needed):

---

2. Color System

Hierarchy through backgrounds, not borders:

• Level 0 (base): --bg-primary — the window background
• Level 1 (sections): --bg-secondary — sidebar, panels
• Level 2 (cards/items): --bg-tertiary or --bg-elevated — content cards
• Level 3 (inputs): slightly different from their container

Use borders sparingly. macOS uses very thin (0.5px), low-opacity borders for subtle definition, never thick or dark ones.

Accent color usage:

• Primary actions (buttons, links, active states)
• Selected items in lists/grids
• Focus rings
• Toggle/switch on-state
• Progress indicators

Never use accent color for large background areas. It's for highlights and interactive elements only.

---

3. Typography

Font stack:

font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
             "Helvetica Neue", Helvetica, Arial, sans-serif;

SF Pro Display for larger text (20px+), SF Pro Text for body (under 20px). The -apple-system stack handles this automatically on macOS.

Type scale (Apple's system):

Notes:

• macOS apps use smaller type than web or mobile. 13px body is standard.
• Letter spacing is tight — Apple uses -0.01 to -0.03em for headlines
• Weight range: Regular (400) for body, Medium (500) for emphasis, Semibold (600) for headings, Bold (700) for large titles
• Use opacity or --text-secondary color for de-emphasized text, not lighter font weight

Monospace (for code, shortcuts, technical):

font-family: "SF Mono", "Menlo", "Monaco", "Courier New", monospace;

---

4. Blur, Vibrancy & Translucency

The defining visual feature of macOS. Sidebars, toolbars, and popovers use translucent backgrounds with blur.

CSS implementation:

/* Sidebar vibrancy */
.sidebar {
  background: rgba(246, 246, 246, 0.72);
  backdrop-filter: saturate(180%) blur(20px);
  -webkit-backdrop-filter: saturate(180%) blur(20px);
}

/* Dark mode sidebar */
@media (prefers-color-scheme: dark) {
  .sidebar {
    background: rgba(30, 30, 30, 0.72);
  }
}

/* Quick-save panel / popover */
.floating-panel {
  background: rgba(255, 255, 255, 0.78);
  backdrop-filter: saturate(180%) blur(20px);
  -webkit-backdrop-filter: saturate(180%) blur(20px);
  border: 0.5px solid rgba(0, 0, 0, 0.1);
  border-radius: 10px;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
}

Where to use blur/vibrancy:

• Sidebars
• Top bars / toolbars
• Floating panels and popovers
• Quick-access windows (Spotlight-style)
• Toast notifications
• Floating action bars

Where NOT to use blur:

• Main content area (this should be solid/opaque for readability)
• Modal backgrounds (use a semi-transparent dark overlay instead)
• Body text containers

Saturation boost: Apple's vibrancy includes saturate(180%) to keep colors from looking washed out behind the blur. Always include this.

---

5. Shadows & Depth

macOS uses layered shadows — multiple stacked shadow values for realistic depth.

Levels:

/* Subtle — cards, buttons */
box-shadow:
  0 0 0 0.5px rgba(0,0,0,0.05),
  0 1px 2px rgba(0,0,0,0.06);

/* Medium — dropdowns, popovers */
box-shadow:
  0 0 0 0.5px rgba(0,0,0,0.06),
  0 4px 16px rgba(0,0,0,0.1);

/* Heavy — floating windows, modals */
box-shadow:
  0 0 0 0.5px rgba(0,0,0,0.1),
  0 2px 8px rgba(0,0,0,0.08),
  0 8px 30px rgba(0,0,0,0.14),
  0 24px 60px rgba(0,0,0,0.08);

/* Window shadow (the main app window) */
box-shadow:
  0 0 0 0.5px rgba(0,0,0,0.1),
  0 12px 40px rgba(0,0,0,0.15),
  0 40px 80px rgba(0,0,0,0.1);

Key detail: The 0 0 0 0.5px border-shadow is essential. It gives subtle definition to edges without using a visible border. This is THE macOS look.

Dark mode shadows: Increase opacity by ~2x since shadows are less visible against dark backgrounds.

---

6. Iconography

Follow SF Symbols design language:

• Monoline stroke style (1.5-2px stroke width)
• Simple, geometric shapes
• 16px default, 20px for prominent actions, 12px for inline hints
• Use currentColor so icons inherit text color
• Slight rounded corners on strokes

Common macOS icons to implement:

• Search: magnifying glass
• Settings: gear
• Share: square with up-arrow
• Add: plus
• Close: × (not a filled circle)
• Back: left arrow
• Sidebar: rectangle split vertically
• Grid/List: grid dots / horizontal lines
• Trash: trash can outline

---

7. Spacing & Sizing

macOS uses an 8px base grid for most spacing.

Common spacings:

Interactive element sizes:

Corner radii: