macos-native-review

macOS native review

Use this skill after a PRD, spec, or implementation plan that contains macOS-specific UI surfaces — before implementation begins. It is NOT a bug hunt, NOT a cross-platform polish review. It is a targeted check that the artifact, if shipped as written, will read as a native Mac app to an experienced Mac user — on the level of Things, Raycast, Linear-mac, Stripe-mac, CleanMyMac — and not as an iOS port.

Every finding cites a specific Apple Human Interface Guidelines page on developer.apple.com. The model fetches HIG pages during review rather than relying on training-data recall, so verdicts are grounded in the current published guidelines.

Invoke with: /superpowers-gstack:macos-native-review

When to invoke

Automatically after completing:

• A PRD, spec, or design document for a macOS app or feature
• An implementation plan that touches macOS UI surfaces
• Output from writing-specs, writing-plans, plan-design-review, plan-eng-review, or any planning skill — when macOS signals are present (see Phase 0)

Run once before implementation. Re-run after substantial spec/plan revisions affecting UI surfaces.

Relationship to pitfall-verification and quality-review

This skill is complementary, not overlapping, with the two existing review skills. Run all three sequentially on a fresh artifact for a macOS app:

| Skill | Lens | Question | |-------|------|----------| | pitfall-verification | Correctness | "Will this work?" (bugs, security, contracts, edge cases) | | quality-review | Perceived quality | "Will this feel good?" (silent failures, loading, empty/error states, polish — cross-platform) | | macos-native-review | Apple-native conformance | "Is this Apple-native?" (HIG-citation-grounded, macOS-specific) |

Recommended flow on a fresh artifact for a macOS app:

1. pitfall-verification → fix bugs
2. quality-review → fix feel
3. macos-native-review → fix native-conformance gaps
4. Hand off to writing-plans / implementation

macos-native-review does not replace quality-review. The latter has 13 platform-independent categories (silent failures, empty states, multi-tenancy, AI output, sort order, etc.) that are still worth running on macOS projects. Modest overlap on two categories (quality-review's keyboard / animations) is acceptable: that skill checks generic conventions, this skill checks Apple-specific values.

Relationship to swiftui-design-consultation

/superpowers-gstack:swiftui-design-consultation is the upstream design-system step for SwiftUI projects. It produces a DESIGN.md + Swift Package starter, then auto-chains into macos-native-review on the DESIGN.md and mcp__swiftui-rag__review_macos_hig on each generated .swift file. The HIG conformance budget set in swiftui-design-consultation Phase 1 is the bar this skill measures against during that chain.

Sequence

1. Phase 0 — macOS signal detection (~30 seconds). Scan the artifact for macOS signals. If none found, return N/A and exit. If iOS-only, return N/A with deferred-skill note. Otherwise proceed.
2. Walk the 12 categories. For each: question → risk surface → verify against HIG page (WebFetch) → cite → report N/A | HANDLED | NOT HANDLED — proposed fix.
3. Produce the verdict in the output format below.

Phase 0 — macOS signal detection

Scan the artifact for any of these signals:

• .swift files referenced in scope
• Imports: SwiftUI, AppKit, Cocoa, Combine (in Apple context)
• Type references: NSWindow, NSView, NSApplication, NSDocument, WindowGroup, MenuBarExtra, Settings scene
• Explicit text: "macOS app", "Mac app", "macOS-native", "AppKit", "SwiftUI for Mac"
• Build target: .xcodeproj with macOS deployment target, Package.swift with .macOS(.v…) platform

Decision:

• No signals found: return N/A — no macOS surfaces detected, skill not applicable and exit. Do not proceed.
• Multi-target (iOS + macOS): proceed. macOS surfaces are relevant.
• iOS-only signals: return N/A — iOS-only project. Use /superpowers-gstack:ios-native-review instead.
• macOS signals present: proceed.

Phase 0 is the safety net for false positives. Without it, the skill would flag "missing ⌘ shortcuts" for a Linux CLI tool.

Category-default HIG URL table

Output this table at the top of every review. Each finding cites either the default URL or a more specific sub-page.

| # | Category | Default HIG URL | |---|----------|------------------| | 1 | Vocabulary | (cross-referenced per-component — cites the HIG page of the component containing the offending text) | | 2 | Buttons & control choices | https://developer.apple.com/design/human-interface-guidelines/buttons | | 3 | Keyboard shortcuts | https://developer.apple.com/design/human-interface-guidelines/keyboards | | 4 | Semantic colors & dark mode | https://developer.apple.com/design/human-interface-guidelines/color, https://developer.apple.com/design/human-interface-guidelines/dark-mode | | 5 | Sheets, popovers, alerts | https://developer.apple.com/design/human-interface-guidelines/sheets, https://developer.apple.com/design/human-interface-guidelines/popovers, https://developer.apple.com/design/human-interface-guidelines/alerts | | 6 | Animation timing | https://developer.apple.com/design/human-interface-guidelines/motion | | 7 | Privileged operations & permission prompts | https://developer.apple.com/design/human-interface-guidelines/privacy | | 8 | Accessibility | https://developer.apple.com/design/human-interface-guidelines/accessibility | | 9 | Menu bar | https://developer.apple.com/design/human-interface-guidelines/the-menu-bar | | 10 | App lifecycle & window restoration | https://developer.apple.com/design/human-interface-guidelines/windows, https://developer.apple.com/design/human-interface-guidelines/the-menu-bar | | 11 | Dock icon behavior (Apple HIG has no standalone Dock page; default URL covers Dock contextual menus only — see citation note in §11 below) | https://developer.apple.com/design/human-interface-guidelines/dock-menus | | 12 | App menu (App > About / Settings… / Quit) | https://developer.apple.com/design/human-interface-guidelines/the-menu-bar |

URLs verified at skill creation. If a URL 404s during review, see "Fallback when developer.apple.com unreachable" below.

The 12 categories

For each category: state the question, locate the risk surface in the artifact, verify by WebFetching the HIG page, and report N/A | HANDLED | NOT HANDLED — proposed fix with citation.

1. Vocabulary

Does copy use Apple-canonical verbs and noun choices? In macOS 13+, "Settings" replaced "Preferences" as the App-menu label. Apple uses Apply / Replace / Save / Done / Cancel, not custom verbs. Apple says "Sidebar", not "Navigation Pane"; "Sheet", not "Modal Dialog". Vocabulary mismatches signal "this app doesn't know the platform".

Risk surfaces: every user-facing string in the spec (button labels, menu items, dialog titles, error messages, empty-state copy).

Cite: the HIG page of the component containing the offending text.

2. Buttons & control choices

Is the chosen control HIG-correct for the surface? Specifically: Picker vs SegmentedControl vs TabView; Sheet vs Popover vs Alert; toolbar buttons vs inline buttons; Toggle vs checkbox-styled button. A Picker used where a Segmented Control belongs reads as iOS-port instantly.

Risk surfaces: every interactive control introduced by the spec.

Cite: https://developer.apple.com/design/human-interface-guidelines/buttons (or sub-pages for specific control types).

3. Keyboard shortcuts

Are macOS-standard shortcuts present and correctly assigned?

• ⌘W — close window (not quit)
• ⌘Q — quit application
• ⌘. — cancel current operation
• ⌘1–9 — switch tabs / sidebar items
• ⌘↩ — primary action in sheet
• Space — quick-look / preview / expand-collapse
• Esc — dismiss sheet / cancel

Missing shortcuts = experienced Mac users h