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:
pitfall-verification→ fix bugsquality-review→ fix feelmacos-native-review→ fix native-conformance gaps- 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
- Phase 0 — macOS signal detection (~30 seconds). Scan the artifact for macOS signals. If none found, return
N/Aand exit. If iOS-only, returnN/Awith deferred-skill note. Otherwise proceed. - Walk the 12 categories. For each: question → risk surface → verify against HIG page (WebFetch) → cite → report
N/A | HANDLED | NOT HANDLED — proposed fix. - Produce the verdict in the output format below.
Phase 0 — macOS signal detection
Scan the artifact for any of these signals:
.swiftfiles referenced in scope- Imports:
SwiftUI,AppKit,Cocoa,Combine(in Apple context) - Type references:
NSWindow,NSView,NSApplication,NSDocument,WindowGroup,MenuBarExtra,Settingsscene - Explicit text: "macOS app", "Mac app", "macOS-native", "AppKit", "SwiftUI for Mac"
- Build target:
.xcodeprojwith macOS deployment target,Package.swiftwith.macOS(.v…)platform
Decision:
- No signals found: return
N/A — no macOS surfaces detected, skill not applicableand 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.
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