# Macos Patterns

> macOS platform patterns: window management, menu bar, keyboard shortcuts, Settings, drag-and-drop, App Sandbox. Use when building macOS-specific features, handling desktop input, or implementing Mac app patterns. Triggers: macOS, Mac, desktop, menu bar, keyboard shortcut, Settings scene, window management.

- Skill: `abdullah4ai/macos-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add abdullah4ai/macos-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abdullah4ai/macos-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: abdullah4ai (https://skillmd.com/u/abdullah4ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/abdullah4ai/macos-patterns

---

# macOS Platform Patterns

## Window Management
Three scene types for Mac apps:
```swift
@main
struct MyApp: App {
    var body: some Scene {
        // Main window — users can open multiple instances
        WindowGroup {
            ContentView()
        }
        .defaultSize(width: 900, height: 600)

        // Single utility window
        Window("Inspector", id: "inspector") {
            InspectorView()
        }
        .defaultSize(width: 300, height: 400)

        // Document-based app
        DocumentGroup(newDocument: MyDocument()) { file in
            DocumentEditor(document: file.$document)
        }
    }
}
```

## Menu Bar Customization (CommandMenu + FocusedValue)
CommandMenu closures run at the App scene level — outside the view hierarchy. They CANNOT access view @State directly. Use @FocusedValue to bridge view state to menu actions.

```swift
// 1. Define a FocusedValue key using @Entry
extension FocusedValues {
    @Entry var activeDocument: DocumentViewModel?
}

// 2. ViewModel — @Observable only (NOT ObservableObject)
@Observable @MainActor
class DocumentViewModel {
    var content = ""
    func save() { /* persist */ }
    func togglePreview() { /* toggle */ }
}

// 3. Publish from active view using .focusedValue()
struct DocumentView: View {
    @State var viewModel = DocumentViewModel()
    var body: some View {
        EditorContent(viewModel: viewModel)
            .focusedValue(\.activeDocument, viewModel)  // REQUIRED — publish to menu bar
    }
}

// 4. Consume in App via @FocusedValue and wire ALL menu actions
@main
struct MyApp: App {
    @FocusedValue(\.activeDocument) private var document

    var body: some Scene {
        WindowGroup { DocumentView() }

        CommandMenu("Document") {
            Button("Save") { document?.save() }
                .keyboardShortcut("s", modifiers: .command)
                .disabled(document == nil)
            Button("Toggle Preview") { document?.togglePreview() }
                .keyboardShortcut("p", modifiers: [.command, .option])
                .disabled(document == nil)
        }

        CommandGroup(replacing: .newItem) {
            Button("New Document") { document?.createNew() }
                .keyboardShortcut("n", modifiers: .command)
                .disabled(document == nil)
        }
    }
}
```

Rules:
- ALWAYS define FocusedValues key using `@Entry` macro
- ALWAYS use `.focusedValue(\.key, value)` on the active view to publish state
- ALWAYS consume via `@FocusedValue(\.key) private var name` in the App struct
- ALWAYS `.disabled(object == nil)` on every menu item — menus are active even when no view is focused
- Using empty closures `{}` on CommandMenu buttons is unacceptable — every action must call through to the FocusedValue
- CommandMenu closures run outside the view hierarchy — they cannot call view methods directly

## Keyboard Shortcuts
Every menu item and primary action needs `.keyboardShortcut()`:
```swift
// Standard shortcuts
Button("Save") { save() }
    .keyboardShortcut("s", modifiers: .command)

Button("Undo") { undo() }
    .keyboardShortcut("z", modifiers: .command)

Button("Find") { showSearch() }
    .keyboardShortcut("f", modifiers: .command)

// Custom shortcuts
Button("Toggle Sidebar") { toggleSidebar() }
    .keyboardShortcut("s", modifiers: [.command, .control])
```

## Settings / Preferences
```swift
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup { ContentView() }

        // Auto-creates "Settings..." in app menu (Cmd+,)
        Settings {
            SettingsView()
        }
    }
}

struct SettingsView: View {
    var body: some View {
        TabView {
            GeneralSettingsView()
                .tabItem { Label("General", systemImage: "gear") }
            AppearanceSettingsView()
                .tabItem { Label("Appearance", systemImage: "paintbrush") }
        }
        .frame(width: 450, height: 300)
    }
}
```

## Menu Bar Apps
```swift
@main
struct StatusApp: App {
    var body: some Scene {
        MenuBarExtra("Status", systemImage: "circle.fill") {
            StatusMenuView()
        }
        .menuBarExtraStyle(.window)
    }
}
```

## Drag and Drop
```swift
// Draggable item
ItemRow(item: item)
    .draggable(item)

// Drop destination
FolderView(folder: folder)
    .dropDestination(for: Item.self) { items, location in
        moveItems(items, to: folder)
        return true
    }
```

## App Sandbox
macOS apps need entitlements for system access:
- File access: `com.apple.security.files.user-selected.read-write`
- Network: `com.apple.security.network.client`
- Camera: `com.apple.security.device.camera`
- Microphone: `com.apple.security.device.audio-input`

## Platform Conditionals
Use for platform-specific code in shared modules:
```swift
#if os(macOS)
import AppKit
// macOS-specific code
#elseif os(iOS)
import UIKit
// iOS-specific code
#endif
```

## Liquid Glass (macOS 26)
```swift
// Translucent glass backgrounds
VStack { content }
    .glassEffect()

// Glass button styles
Button("Action") { }
    .buttonStyle(.glass)

Button("Primary") { }
    .buttonStyle(.glassProminent)
```

## File Handling
```swift
// Open panel
.fileImporter(
    isPresented: $showOpen,
    allowedContentTypes: [.json]
) { result in
    // handle
}

// Save panel
.fileExporter(
    isPresented: $showSave,
    document: doc,
    contentType: .json
) { result in
    // handle
}
```

## Deprecated API Alternatives
- Use `.foregroundStyle()` not `.foregroundColor()`
- Use `.clipShape(.rect(cornerRadius:))` not `.cornerRadius()`
- Use `@Observable` not `ObservableObject` — never combine both on the same class
- Touch Bar is deprecated — do not implement

## NOT Available on macOS
- No UIKit — macOS uses AppKit; SwiftUI apps should never import UIKit
- No `UIColor` / `UIImage` — use SwiftUI `Color` / `Image` instead
- No HealthKit
- No haptic feedback (CoreHaptics)
- No rear camera, LiDAR, or portrait mode (FaceTime camera only)
- No App Clips
- No Live Activities
- No Safari extensions (different extension model)

## Rules
1. Use `WindowGroup`, `Window`, or `DocumentGroup` for scene types
2. Use `CommandMenu` / `CommandGroup` for menu bar customization
3. Every primary action MUST have `.keyboardShortcut()`
4. Use `Settings { }` scene for preferences (auto-wires Cmd+,)
5. Use `MenuBarExtra` for menu bar apps with `.menuBarExtraStyle(.window)`
6. Use `.draggable()` / `.dropDestination()` for drag-and-drop
7. Use `#if os(macOS)` for platform-specific code in shared modules
8. Never import UIKit — use SwiftUI `Color`/`Image` not `NSColor`/`NSImage`
9. Use `.foregroundStyle()` not `.foregroundColor()`
10. Use `.clipShape(.rect(cornerRadius:))` not `.cornerRadius()`