macos-patterns

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass, no license.

Audit 0.4.1 · source sha d0a46479b2fe · 23 Oct 2026Report an issue or request a re-scan

• Publisherfayazara GitHub userOwner of the repository this skill is read from
• Source folderfayazara/macos-app-skills/macos-patternsThe exact folder we audited
• LicenceNot declaredAs the repository states it
• Commit pinned for this verdictd0a46479b2feA new audit runs when the source changes
• Repository statusNot archivedLast push 148 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Essential native macOS development patterns that web developers don't know about. Use this skill whenever the user is building a macOS app and needs guidance on native patterns, or when they ask about menu bar apps,…

---
name: macos-patterns
description: >
  Essential native macOS development patterns that web developers don't know about. Use this skill
  whenever the user is building a macOS app and needs guidance on native patterns, or when they ask
  about menu bar apps, floating panels, window levels, keyboard shortcuts, file pickers, clipboard,
  drag and drop, screen capture, activation policy, Quick Look, launch at login, or any macOS-specific
  API. Also trigger when the user seems to be applying web development patterns to macOS (e.g., using
  z-index thinking for windows, expecting simple clipboard APIs, or not understanding focus/activation).
  This is the "how things actually work on macOS" reference that prevents the AI from generating
  confident but wrong code. Use this skill proactively whenever building any native macOS app.
---

# Native macOS Patterns for Web Developers

This is a reference guide for the macOS-specific patterns that have no web equivalent. When building a native macOS app, these are the things that trip up everyone coming from web development. The AI should consult this before generating macOS code to avoid confidently producing patterns that don't work.

## Menu Bar Apps

There are two approaches. Use `MenuBarExtra` for simple menus, `NSStatusItem` for full control.

### SwiftUI MenuBarExtra (simple)

```swift
@main
struct MyApp: App {
    var body: some Scene {
        MenuBarExtra("MyApp", image: "MenuBarIcon") {
            MenuBarView()
        }
    }
}
```

This creates a menu-bar-only app. The menu content is a standard SwiftUI view. For a popover-style menu bar app (richer UI than a plain menu), use the `.window` style:

```swift
MenuBarExtra("MyApp", image: "MenuBarIcon") {
    PopoverContentView()
}
.menuBarExtraStyle(.window)
```

### AppKit NSStatusItem (full control)

For custom menus, dynamic icons, or complex interactions:

```swift
let statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)
if let button = statusItem.button {
    let icon = NSImage(named: "MenuBarIcon")!
    icon.size = NSSize(width: 18, height: 18)
    icon.isTemplate = true  // CRITICAL: adapts to dark/light mode automatically
    button.image = icon
}

let menu = NSMenu()
menu.addItem(NSMenuItem(title: "Settings...", action: #selector(openSettings), keyEquivalent: ","))
statusItem.menu = menu
```

`isTemplate = true` is essential. Without it, your icon will be invisible in light mode or look wrong in dark mode.

### NSPopover for Rich Menu Bar Content

For a popover attached to the menu bar icon (like Bartender, iStatMenus):

```swift
let popover = NSPopover()
popover.contentSize = NSSize(width: 300, height: 400)
popover.behavior = .transient  // auto-closes when clicking outside
popover.contentViewController = NSHostingController(rootView: MyPopoverView())

// Show from the status item button:
if let button = statusItem.button {
    popover.show(relativeTo: button.bounds, of: button, preferredEdge: .minY)
}
```

## Activation Policy -- Dock Icon Toggling

A macOS app can dynamically show/hide its Dock icon and Cmd-Tab presence at runtime. Menu-bar-only apps start as `.accessory` (invisible in Dock) and temporarily become `.regular` when they open windows like Settings.

```swift
// At launch -- hide from Dock:
NSApp.setActivationPolicy(.accessory)

// When opening a window -- show in Dock:
NSApp.setActivationPolicy(.regular)
NSApp.activate(ignoringOtherApps: true)

// When closing the last window -- hide again:
NSApp.setActivationPolicy(.accessory)
```

Use reference counting if multiple windows can be open simultaneously:

```swift
@MainActor
enum AppActivationPolicy {
    private static var count = 0

    static func enter() {
        count += 1
        NSApp.setActivationPolicy(.regular)
        NSApp.activate(ignoringOtherApps: true)
    }

    static func leave() {
        count = max(0, count - 1)
        guard count == 0 else { return }
        Task { @MainActor in NSApp.setActivationPolicy(.accessory) }
    }
}
```

## NSPanel vs NSWindow

`NSPanel` is a subclass of `NSWindow` for auxiliary content that should not steal focus. Use it for:

- Floating overlays (preview cards, recording indicators)
- Palettes and tool windows
- Inspectors
- Anything that should stay visible while the user works in another app

Key configuration:

```swift
let panel = NSPanel(
    contentRect: .zero,
    styleMask: [.borderless, .nonactivatingPanel],  // Does NOT steal focus
    backing: .buffered,
    defer: false
)
panel.isOpaque = false
panel.backgroundColor = .clear
panel.hasShadow = false
panel.hidesOnDeactivate = false     // Stay visible when app loses focus
panel.isFloatingPanel = true        // Float above normal windows
panel.ignoresMouseEvents = true     // Clicks pass through to windows below
panel.collectionBehavior = [
    .canJoinAllSpaces,              // Visible on all virtual desktops
    .fullScreenAuxiliary,           // Visible over fullscreen apps
]
```

To host SwiftUI content in the panel:

```swift
let hostingView = NSHostingView(rootView: MySwiftUIView())
panel.contentView = hostingView
```

Override focus behavior when needed:

```swift
class MyPanel: NSPanel {
    override var canBecomeKey: Bool { true }     // Can receive keyboard input
    override var canBecomeMain: Bool { false }   // Never becomes the "main" window
}
```

### Screen Capture Exclusion

If your app shows floating UI that shouldn't appear in screenshots/recordings:

```swift
panel.sharingType = .none  // Invisible to screen capture APIs
```

## Window Levels

macOS has a multi-tier window level system that controls where windows appear relative to the entire OS (not just your app):

```
normal (0)           -- standard app windows
floating (3)         -- tool palettes, floating panels
modalPanel (8)       -- modal dialogs
mainMenu (24)        -- menu bar
screenSaver (1000)   -- above everything except...
CGShieldingWindowLevel() -- above absolutely everything (kiosk m

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-23
   ✓SAFE B 89 / 100

   first audit · source d0a46479b2fe

Questions about macos-patterns

• github.com/fayazara/macos-app-skills/tree/main/macos-patterns — the audited source at commit d0a46479b2fe and every finding aboveObserved · 23 Oct 2026

Spotted something wrong? Report a correction · Methodology