apple-native-review

After a PRD/spec/plan for a native Apple app (macOS, iOS, iPadOS), before implementation: validate it against Apple HIG with fetched citations. Asks "is this Apple-native?" — complements pitfall-verif

SKILL.md

GitHub

Apple native review

Run this after a PRD, spec, design document, or implementation plan that describes UI for a macOS, iOS, or iPadOS app, and before implementation starts. It asks one question: if this artifact ships as written, will it read as a native app to an experienced Mac or iPhone user, rather than as a port from another platform?

Every finding cites an Apple Human Interface Guidelines (HIG) page that was fetched during this run. Invoke with /superpowers-gstack:apple-native-review; the artifact is read from context or from the path given in the arguments. Run once per artifact and re-run after revisions that touch UI surfaces.

Where it sits

Skill Question
/superpowers-gstack:pitfall-verification Will it work? (bugs, contracts, security, edge cases)
/superpowers-gstack:quality-review Will it feel good? (loading, empty and error states, polish; cross-platform)
/superpowers-gstack:apple-native-review Is it Apple-native? (HIG conformance, per platform)

Recommended order on a fresh artifact: pitfall-verification, quality-review, apple-native-review, then hand off to superpowers:writing-plans or implementation. quality-review's platform-independent categories still apply to Apple projects; the small overlap on keyboard and animation is deliberate, since that skill checks generic conventions and this one checks Apple's specific values.

/superpowers-gstack:swiftui-design-consultation is the upstream design-system step; it chains into this skill on its DESIGN.md with the platform track already set.

Phase 0 — platform self-check

  1. Read .gstack/track if it exists. macos, ios, or both names the platform(s) to review.
  2. Otherwise, or to confirm, scan the artifact:
    • macOS signals: AppKit, Cocoa, NSWindow, NSView, NSApplication, NSDocument, MenuBarExtra, a Settings scene, .macOS(.v…) in Package.swift, a macOS deployment target, or text such as "Mac app" or "macOS-native".
    • iOS/iPadOS signals: UIKit, UIViewController, UIScene, UIApplicationSceneManifest, .fullScreenCover, .iOS(.v…), an iOS deployment target, or text such as "iPhone app", "iPad app", "iPadOS".
    • SwiftUI, WindowGroup, TabView, NavigationStack and NavigationSplitView are cross-platform and identify neither; look for one of the above.
  3. Decide. The track file sets the baseline; artifact signals can add a platform (a multi-target project) but never remove one from the project. Within a both project, the artifact decides which lists apply to it: an artifact whose own signals name only one platform is reviewed against the shared categories plus that platform's list — a menu-bar finding on an iPhone-only feature is noise, not conformance.
    • No track file and no signals: report Verdict: N/A — no Apple UI surfaces detected and stop.
    • Signals only for watchOS, tvOS, or visionOS: report N/A naming the platform; those are out of scope.
    • Otherwise list the platform(s) under review and continue. For both, walk the shared categories once and each platform-specific list once.

Phase 0 is what keeps the skill from flagging a missing menu bar in a Linux CLI tool.

Citations

Every finding cites a HIG page fetched in this run, with a short verbatim quote (about 10–25 words). Training-data recall is never presented as a citation. If a page cannot be fetched, the finding is tagged (uncited) and the verdict becomes PROVISIONAL.

Sources, in the order they are consulted:

  1. The HIG page itself (the citation). HIG pages live at https://developer.apple.com/design/human-interface-guidelines/<slug>. That HTML is a JavaScript-rendered shell that returns only a title, so fetch the structured form instead: WebFetch https://developer.apple.com/tutorials/data/design/human-interface-guidelines/<slug>.json with a prompt that demands verbatim passages under their section headings and refuses to summarise — WebFetch otherwise returns a processed summary, and a paraphrase satisfies the citation format without being one. If the tool returns prose instead of quoted passages, tag the finding (paraphrased) and treat it as uncited for the verdict. Cite the HTML URL in the finding.
  2. API reference, when the fix names an API. mcp__apple-docs__search_apple_docs to find the page, mcp__apple-docs__get_apple_doc_content to read it (availability, declaration, discussion). This server covers developer.apple.com/documentation/…; it does not serve HIG pages, so it supplements a HIG citation rather than replacing it.
  3. Current platform idiom. mcp__swiftui-rag__search_swiftui_corpus with platform set, to check what the SwiftUI idiom for the surface looks like before proposing a fix.

Categories

All HIG slugs below resolve under https://developer.apple.com/design/human-interface-guidelines/. macOS reviews S1–S6 plus M1–M6 (12 categories); iOS/iPadOS reviews S1–S6 plus I1–I7 (13). For each category: state the question, locate the risk surface in the artifact, fetch the page, and report N/A | HANDLED | NOT HANDLED — proposed fix.

Shared (both platforms)

# Category HIG slug Check Platform difference
S1 Vocabulary the page of the component holding the text Apple's verbs: Done, Cancel, Save, Delete, Add, Apply, Replace. No custom verbs. macOS: "Settings…" not "Preferences" (macOS 13+), "Sidebar" not "Navigation Pane". iOS: "Tab bar" not "Bottom Navigation", "Sheet" not "Bottom Sheet", "Navigation bar" not "App bar".
S2 Semantic colors & dark mode color, dark-mode Status and background colors are semantic and adapt to appearance; dark mode is addressed, not assumed away. macOS: Color(NSColor.systemBlue), window and under-page backgrounds. iOS: Color(.systemBackground) / .systemGroupedBackground hierarchy, Color(.label).
S3 Animation timing motion Named easing (.snappy, .smooth, .bouncy, a tuned .spring) over default .easeInOut; transitions chosen per surface. Same rule on both; iOS additionally respects Reduce Motion with a fade instead of a slide.
S4 Privileged operations & permission prompts privacy (iOS also onboarding) Explanation before the system prompt, requested just-in-time, with a real sentence as rationale. Never a toast, never on launch. macOS: TCC (Full Disk Access, Accessibility, Screen Recording, Automation) and admin authorization. iOS: Location, Camera, Microphone, Photos, Notifications, Contacts, ATT pre-prompt; NS…UsageDescription strings are sentences.
S5 Accessibility accessibility VoiceOver labels on non-text controls, Dynamic Type (no fixed sizes), adequate contrast, .accessibilityLabel / .accessibilityHint / .accessibilityValue on custom controls. macOS: Full Keyboard Access for non-trivial flows. iOS: Dynamic Type up to AX5, Reduce Motion, rotor navigation on complex screens.
S6 App lifecycle & state restoration macOS: windows, the-menu-bar. iOS: launching, multitasking People return where they left off; long-running work survives backgrounding. macOS: ⌘Q quits and ⌘W closes; closing the last window does not quit; "Reopen All Windows" restores state. iOS: scene lifecycle, multi-window on iPadOS, BGAppRefreshTask / background URLSession, launch screen matches the first content screen (no logo splash).

macOS-only

# Category HIG slug Check
M1 Buttons & control choices buttons (or the control's own page) Picker vs segmented control vs TabView; sheet vs popover vs alert; toolbar vs inline buttons; Toggle vs checkbox. A Picker where a segmented control belongs reads as an iOS port.
M2 Keyboard shortcuts keyboards ⌘W close window, ⌘Q quit, ⌘. cancel, ⌘1–9 switch tabs or sidebar items, ⌘↩ primary action in a sheet, Space quick look, Esc dismiss. Missing shortcuts feel broken to a Mac user.
M3 Sheets, popovers, alerts sheets, popovers, alerts Sheet for window-scoped modal flows (Cancel plus primary button); popover for transient content anchored to an element (click-outside dismiss); alert for critical decisions (Cancel plus destructive action).
M4 Menu bar the-menu-bar App, File, Edit, View (if applicable), Window, Help exist; commands sit in the conventional menu (Find under Edit, not View); shortcuts annotated.
M5 Dock dock-menus for the contextual menu; other Dock behavior has no single HIG page, so cite the closest component page and mark the citation partial Clicking the Dock icon reactivates the main window; dock menu and badges where relevant; menu-bar-only utilities declare LSUIElement so no Dock icon shows.
M6 App menu the-menu-bar About <App>, Settings…, Hide / Hide Others / Show All, Quit <App>; the About panel shows version, build, and copyright.

iOS/iPadOS-only

# Category HIG slug Check
I1 Controls & touch targets buttons Hit regions of at least 44×44 pt, especially icon-only buttons, tab items, and row actions. Right control per surface: Button vs Menu vs Picker, Stepper for fine numeric input, segmented control for ≤6 options.
I2 Navigation paradigm tab-bars, navigation-bars TabView for ≤5 peer destinations, NavigationStack for drill-down, NavigationSplitView on iPad; large title on root screens, inline on drill-down; the back button shows the previous title.
I3 Modal presentation sheets, popovers, alerts .sheet with .presentationDetents where a mid-size fits and .presentationDragIndicator(.visible); .fullScreenCover for immersive flows; .popover only in the regular size class; .interactiveDismissDisabled() guarding unsaved input.
I4 Gestures gestures Swipe-back from the left edge stays enabled; .refreshable, .swipeActions, .contextMenu where lists need them; custom gestures do not collide with system edge gestures.
I5 System surfaces layout, live-activities Safe areas respected (ignoresSafeArea is opt-in); status bar style matches the background; Live Activity / Dynamic Island considered for background timers, audio, and navigation.
I6 Keyboard handling onscreen-keyboards .keyboardType and .textContentType paired per field; .submitLabel set; keyboard dismissable; the focused field scrolls above the keyboard.
I7 Haptics playing-haptics Haptics on outcomes (.notificationOccurred), selection (.selectionChanged), and impact; absent haptics feel silent, haptics on every tap fatigue.

How to run each category

  1. State the question in one sentence.
  2. Locate the risk surface: which spec section, file, or user flow.
  3. Fetch the HIG page and capture the quote that supports or contradicts the artifact's choice.
  4. Report N/A (with reason), HANDLED (point to where), or NOT HANDLED with a fix that names a file, function, or spec section, plus the citation.

Concrete findings only; "follow the HIG more closely" is not a finding. Optionally name one Apple-tier peer app the bar was set against (Things, Raycast, Bear, Overcast).

Severity

  • CRITICAL — first launch reads as the wrong platform. macOS: ⌘Q only closes a window, no menu bar, "Preferences" in the App menu, a sheet with no dismiss. iOS: a custom bottom bar instead of TabView, a sheet with no dismiss, a permission prompt on launch with no rationale, content under the Dynamic Island or home indicator, swipe-back disabled. Both: hardcoded colors that fail in dark mode.
  • SIGNIFICANT — works, but an experienced user reads it as a port within a week. macOS: missing ⌘1–9, Picker where a segmented control belongs, an admin prompt framed as a toast. iOS: Material vocabulary, no haptics on confirmations, no .textContentType on credential fields, no pull-to-refresh on a list that needs it. Both: default .easeInOut on sheet present/dismiss, usage-description strings that are tokens rather than sentences.
  • POLISH — the gap to Apple-tier apps. macOS: no hover state on toolbar buttons, an About panel missing copyright or build. iOS: no drag indicator on a dismissible sheet, a logo splash as launch screen, no Dynamic Island on an obvious background task. Both: timing close to but not exactly Apple's defaults.

Be honest about severity; POLISH is not escalated to force a fix.

Output format

Apple native review (HIG-citation-grounded) —

Platform(s) reviewed: macOS | iOS/iPadOS | both   (source: .gstack/track | artifact signals)
Pages fetched this run: <slug>, <slug>, …

CRITICAL (will feel like the wrong platform on first launch):
- C<N>. <finding> — <risk surface: file:line or spec section>
  → <fix anchored to a file or section>
  Cited: <HIG URL> "<verbatim quote>"

SIGNIFICANT (works, but reads as a port within the first week):
- S<N>. <finding> → <fix>
  Cited: <HIG URL> "<quote>"

POLISH (gap to Apple-tier):
- P<N>. <finding> → <fix>
  Cited: <HIG URL> "<quote>"

Verdict: SHIP-READY | NEEDS PATCH | NEEDS POLISH | PROVISIONAL | N/A

SHIP-READY hands off to implementation. NEEDS PATCH means fix the CRITICAL findings and re-run. NEEDS POLISH is surfaced to the user with a fix-now-or-defer choice, deferred items tracked as a debt note. PROVISIONAL means one or more pages could not be fetched; the user decides whether to proceed. For both, produce one report with each finding tagged [macOS] or [iOS].

Worked example

C1. [macOS] App menu uses "Preferences" instead of "Settings". Spec §3.2
("App menu structure") lists "Preferences…". Apple renamed the item to
"Settings…" in macOS 13; apps still using "Preferences…" read as
un-updated.

Risk surface: spec §3.2; the menu declaration (likely a SwiftUI
`Settings` scene or `AppMenu.swift`).

Fix: change spec §3.2 to "Settings…". Use SwiftUI's `Settings { }`
scene, which labels the menu correctly on macOS 13+.

Cited: https://developer.apple.com/design/human-interface-guidelines/the-menu-bar
App menu, standard items: "Settings… — Opens your settings window, or
your app's page in iPadOS Settings."

That is the bar: spec section, code pointer, concrete fix, and a verbatim quote with its URL.

What this skill is NOT

  • Not a bug hunt: /superpowers-gstack:pitfall-verification.
  • Not a cross-platform polish review: /superpowers-gstack:quality-review.
  • Not a security audit of entitlements or sandboxing: /cso.
  • Not a review of a running UI (/design-review), a plan-level design review (/plan-design-review), or a developer-experience review (/plan-devex-review).
  • Not release engineering: signing, notarization, App Store submission, TestFlight.
  • Not watchOS, tvOS, visionOS, Windows, or Android; those are separate skills, deferred in IDEAS.md.
  • Not a code-level SwiftUI review. Run this on the spec, then swiftui-expert-skill (Antoine van der Lee's plugin) on the implementation.