Build, audit, or ship native macOS SwiftUI/AppKit apps with HIG compliance, Liquid Glass visual treatment, expectation-first visual validation, Swift quality hooks, and optional Convex + Clerk cloud sync.
This file is the spine. Match the request to one Operation in the table below, then load only the references for that branch — do not preload the whole tree.
When to use this skill
Trigger on any of:
- Native macOS app work: new app scaffolds, feature implementation, redesigns, audits, migrations, release prep, or quality setup.
- SwiftUI/AppKit projects with
*.xcodeproj,*.xcworkspace,Package.swift, or Swift files that include a macOS app target. - macOS UI concerns: menus, keyboard shortcuts, windows, sidebars, toolbars, settings, accessibility, HIG conformance, Liquid Glass, snapshot tests, SwiftLint, SwiftFormat, or pre-commit hooks.
- Multi-platform Apple repos when a macOS target exists.
- Convex + Clerk Swift client work when the app has a macOS surface.
Example user phrases that should trigger this skill:
- "Make this Mac app feel native — it looks like an iOS app on a Mac."
- "Audit this SwiftUI macOS app against the HIG and the Liquid Glass guidelines."
- "Migrate this Mac app from macOS 14 to Tahoe / macOS 26."
- "Wire SwiftLint, SwiftFormat, and a pre-commit hook into this Swift repo."
- "Add
swift-snapshot-testingto this macOS app and capture screenshots in CI." - "Hook up Convex + Clerk to my SwiftUI Mac app with reactive queries and SIWA."
- "Build a
MenuBarExtraapp with Settings, command menu, and Cmd-Q wired up." - "Why does this Liquid Glass toolbar look wrong on macOS 26?"
- "Pre-release checklist for shipping this Mac app."
Do NOT use this skill for:
- iOS-only, iPadOS-only, visionOS-only, watchOS-only, or tvOS-only work without a macOS target.
- Generic Swift package work with no app, UI, or macOS surface (use the language-level skill set).
- Pure server-side Convex, TypeScript, or backend-only work — even if the same product has a Mac client, route backend-only requests away.
- Non-Apple Swift on Linux, Windows, or server-side Swift.
- Browser automation or web snapshot testing — route to browser or Playwright skills.
- Catalyst-only or Intel-Mac targets for the Convex + Clerk path (current ConvexMobile is Apple Silicon only).
- Generic Swift quality-hook setup for a repo with no macOS target — the per-platform references for iOS, tvOS, watchOS, and visionOS exist only to support multi-platform Apple repos that also include macOS.
If a request is ambiguous (e.g. "I'm building an Apple app"), confirm there is a macOS target before engaging.
Platform Stance
| Scope | Rule |
|---|---|
| Primary scope | Native macOS SwiftUI/AppKit apps. |
| Multi-platform repos | In scope only when a macOS target exists. |
| Out of scope | iOS-only, iPadOS-only, visionOS-only, watchOS-only, tvOS-only, non-Apple Swift, and pure server-side Convex. |
| Liquid Glass target | macOS 26+ with the Xcode 26 SDK. |
| Backward-compatible target | macOS 14+ with availability guards where Liquid Glass or Clerk paths require them. |
| Clerk + Convex path | Apple Silicon macOS only per current ConvexMobile limitations. |
HIG vs Liquid Glass
HIG is the baseline that always applies. Liquid Glass is an additive, version-gated visual treatment layered on top of an HIG-correct view — never a substitute for it.
| Decision | Apply |
|---|---|
| Interaction, menus, windows, keyboard shortcuts, settings, accessibility, typography, spacing, and standard controls | HIG is always the baseline. |
| macOS 26 / Tahoe-era visual treatment for navigation, chrome, toolbars, sidebars, floating controls, sheets, popovers, and overlays | Liquid Glass may apply after HIG is satisfied. |
| Content rows, text, tables, form fields, cards, and data surfaces | Never apply glass. Keep content readable and semantically styled. |
| macOS 14/15 support | Gate Liquid Glass APIs with #available(macOS 26, *); provide NSVisualEffectView or standard SwiftUI fallbacks. |
Operations
Detect the operation from the user's request, then load the narrowest reference set. Each row routes to the entry point — that file may fan out into siblings, but the spine never preloads them.
| Operation | Trigger phrase / signal | Route |
|---|---|---|
| Bootstrap | New macOS app, fresh project, or first production scaffold | references/workflow/bootstrap-new-app.md |
| Build | "Add a screen / view / window / command", any new feature on an existing app | Apply the Three Questions, then route by subsystem in HIG / Liquid Glass routing tables below |
| Redesign | "Make it native", "Apple-like", "Tahoe-ready", "make it Liquid Glass" | references/liquid-glass/design-diagnosis.md |
| Audit | "Review", "assess", "find issues", "preflight", "lint the design" | references/workflow/audit-existing.md |
| Migrate | Pre-Tahoe code (macOS 14/15) moving to macOS 26 | references/liquid-glass/migration-guide.md |
| Install hooks | "Set up SwiftLint / SwiftFormat / pre-commit / CI quality" | references/quality-hooks/hook-architecture.md |
| Add visual tests | "Snapshot tests", "screenshot validation", "visual diff" | references/visual-validation/snapshot-testing-spm.md |
| Wire cloud sync | Convex, Clerk, real-time queries, subscriptions, or auth-gated data | references/cloud-sync/overview.md |
| Ship | Release checklist, App Store, direct distribution, notarization | references/workflow/ship-checklist.md |
If the requested operation is ambiguous, make the smallest reasonable assumption and proceed; do not stall for confirmation on routine work.
Core Guardrails
These four rules and the Three Questions are the gate every Build operation must pass before any view code is written or modified.
Three Laws Of macOS UI
- Every action must be reachable from the menu bar; toolbars are optional chrome. See references/hig/components/menus.md.
- Standard keyboard shortcuts are reserved:
Cmd-N/O/S/Shift-S/Z/Shift-Z/Q/W/Comma/F/A/C/V/X. See references/hig/platform/keyboard-shortcuts.md. - Settings take effect immediately. No Save, Cancel, or Apply buttons in preferences. See references/hig/components/menus.md.
Three Questions Before Any View
- Is this navigation or content?
- What is the one primary action?
- Would this feel native beside Finder, Mail, Photos, or Settings?
If a request would violate any of the Three Laws, or any of the Three Questions has no clear answer, redesign before writing code.
Critical audit findings — route by smell
| Finding | Route |
|---|---|
| Glass on content, list rows, cards, table cells, or text | references/liquid-glass/design-principles.md |
| Multiple tinted primary actions on one screen | references/liquid-glass/design-principles.md |
| Hardcoded colors, fixed font sizes, iOS-scale rows, or custom dark-mode toggles | references/hig/foundations/color-and-dark-mode.md, references/hig/foundations/typography.md |
NavigationView, missing Settings, missing commands, custom window chrome, or missing shortcuts |
references/hig/platform/windows.md, references/hig/platform/toolbars.md, references/liquid-glass/design-diagnosis.md |
| AppKit/SwiftUI ceiling confusion | references/liquid-glass/appkit-bridging.md, references/hig/practitioner-insights.md |
HIG Reference Routing
Open the row that matches the topic in the request. Foundations cover how things look; components cover individual controls; platform covers window-level structure; technologies covers system integrations.
| Need | Read |
|---|---|
| Color, dark mode, semantic colors, and layer adaptation | references/hig/foundations/color-and-dark-mode.md |
| Typography, weights, SF Pro Text vs Display | references/hig/foundations/typography.md |
| Spacing, alignment, 8pt grid, control size decisions | references/hig/foundations/layout-spacing.md |
| Icons, app icons, SF Symbols, animation | references/hig/foundations/icons-and-sf-symbols.md |
Materials, vibrancy, .behindWindow, .withinWindow |
references/hig/foundations/materials-and-vibrancy.md |
| Motion timing, springs, Reduce Motion | references/hig/foundations/motion.md |
| Buttons and button hierarchy | references/hig/components/buttons.md |
| Text fields, search fields, labels, validation | references/hig/components/text-inputs.md |
| Pickers, sliders, steppers, toggles, checkboxes | references/hig/components/selection-controls.md |
| Menus, menu bar, contextual menus, Services | references/hig/components/menus.md |
| Popovers, tooltips, disclosure, inspectors | references/hig/components/popovers-and-disclosure.md |
| Tables, lists, outlines, collection views | references/hig/components/tables-and-lists.md |
| Alerts, sheets, dialogs, destructive actions | references/hig/components/alerts-and-sheets.md |
| Windows, restoration, tabbing, traffic lights | references/hig/platform/windows.md |
| Sidebars, split views, source lists, inspectors | references/hig/platform/sidebars-and-split-views.md |
| Toolbars, title bars, customization | references/hig/platform/toolbars.md |
| Keyboard shortcuts, focus, Escape hierarchy | references/hig/platform/keyboard-shortcuts.md |
| Drag/drop, pasteboard, file promises, documents | references/hig/platform/drag-drop-files.md |
| Accessibility, VoiceOver, contrast, motion | references/hig/technologies/accessibility.md |
| Widgets, notifications, Spotlight, MenuBarExtra | references/hig/technologies/widgets-and-notifications.md |
| Practitioner overrides and common real-world judgment calls | references/hig/practitioner-insights.md |
Liquid Glass Routing
Read these only after HIG is satisfied for the view in question. Glass is a finishing layer, not a structural one.
| Need | Read |
|---|---|
| SwiftUI and AppKit API surface | references/liquid-glass/api-reference.md |
| Navigation/content divide, concentricity, tint hierarchy | references/liquid-glass/design-principles.md |
| Deprecated APIs, smell catalog, audit heuristics | references/liquid-glass/design-diagnosis.md |
| Toolbar, sidebar, window, Settings recipes | references/liquid-glass/macos-patterns.md |
| Pre-Tahoe migration sequence | references/liquid-glass/migration-guide.md |
| Known bugs, crashes, and workarounds | references/liquid-glass/pitfalls-and-solutions.md |
| AppKit and SwiftUI bridge choices | references/liquid-glass/appkit-bridging.md |
Liquid Glass references carry WWDC 2025 session context. Do not duplicate session lists in the spine.
Visual Validation Routing
Expectation-first discipline (decide what should be true, then look) is separate from the pixel-diff library (the SPM tool that captures and compares images). Use both; do not skip the discipline.
| Need | Read |
|---|---|
| Expectation-first loop and report buckets | references/visual-validation/expectation-loop.md |
| Capture-mode selection for native, hybrid, and fallback paths | references/visual-validation/capture-modes.md |
| Drift taxonomy and narrowest-layer fix choice | references/visual-validation/drift-analysis.md |
Point-Free swift-snapshot-testing SPM wiring, record/verify mode, CI artifacts |
references/visual-validation/snapshot-testing-spm.md |
| Blank screenshots, focus failures, permissions, unstable runners | references/visual-validation/troubleshooting.md |
Quality Hooks Routing
Hard guardrails:
- Never write to
.git/hooks/directly; usegit config core.hooksPath .githooks. - Never enable typecheck stage by default; opt in with
SWIFT_HOOK_TYPECHECK=1. - Never install global tools without confirmation.
- Never commit an empty SwiftLint baseline as a legacy-project solution.
- Never claim typecheck works without running it once end to end.
Copy the bundled assets from the outer skill root into the target repo:
| Source | Destination | Purpose |
|---|---|---|
assets/swiftlint.yml |
.swiftlint.yml |
SwiftLint rules and custom rules |
assets/swiftformat |
.swiftformat |
SwiftFormat allowlist |
assets/githooks/pre-commit |
.githooks/pre-commit |
Staged Swift lint/format/typecheck hook |
assets/scripts/swift-typecheck.sh |
scripts/swift-typecheck.sh |
Per-platform xcodebuild matrix |
assets/Makefile.fragment |
append to Makefile |
Lint, format, hook install targets |
assets/github-workflows/swift-quality.yml |
.github/workflows/swift-quality.yml |
CI matrix and snapshot artifacts |
| Need | Read |
|---|---|
| Hook architecture and install semantics | references/quality-hooks/hook-architecture.md |
| Greenfield vs legacy SwiftLint baselines | references/quality-hooks/baseline-workflow.md |
| Opt-in typecheck stage and project detection | references/quality-hooks/typecheck-stage.md |
| SwiftLint config rationale | references/quality-hooks/configs/swiftlint-config.md |
| SwiftFormat config rationale | references/quality-hooks/configs/swiftformat-config.md |
| Hook troubleshooting | references/quality-hooks/troubleshooting.md |
| macOS typecheck destination | references/quality-hooks/platforms/macos.md |
| Multi-platform Apple CI matrix | references/quality-hooks/platforms/multiplatform.md |
| iOS companion targets in macOS repos | references/quality-hooks/platforms/ios.md |
| tvOS companion targets in macOS repos | references/quality-hooks/platforms/tvos.md |
| watchOS companion targets in macOS repos | references/quality-hooks/platforms/watchos.md |
| visionOS companion targets in macOS repos | references/quality-hooks/platforms/visionos.md |
Cloud Sync Routing
Engage only when Package.swift or the request mentions ConvexMobile, ClerkKit, ClerkConvex, Convex, Clerk, real-time queries, multi-device sync, auth-gated cloud data, or live subscriptions. Skip this track for local-only Core Data or SwiftData apps.
Default stance:
- Use Clerk as the default Swift auth path.
- Treat
clerk-convex-swift >= 0.1.0,clerk-ios >= 1.0.0, andconvex-swift >= 0.8.0as minimum supported bounds; use version audit notes in references/cloud-sync/operations/verified-corrections.md for latest checked versions. - Prefer one
@MainActorlong-lived authenticated client per process:ConvexClientWithAuth(deploymentUrl:authProvider: ClerkConvexAuthProvider()). - Use
AuthView()andUserButton()fromClerkKitUI; do not roll a manual SIWA flow aroundASAuthorizationController. - Treat the Swift SDK as reconnecting-online, not offline-first.
- Treat macOS support as Apple Silicon only through this stack.
Hard rules:
- Do not promise optimistic updates, native offline persistence, Catalyst, Intel Mac, watchOS, tvOS, or visionOS support for ConvexMobile.
- Do not trust client-passed
userIdvalues. Server-side Clerk JWT identity is the authorization boundary. - Do not use
Date.now()inside Convex queries; pass stable client timestamps. - Do not assume a subscription recovers after terminal Combine failure; rebuild with
resubscribe(). - Do not declare subscription-owning view models at the App scene level on macOS; use per-window or in-hierarchy ownership.
Cloud Sync Start Points
| Decision | Read |
|---|---|
| Whole corpus map and narrow routing | references/cloud-sync/overview.md |
| Current limitations and hard stops | references/cloud-sync/limitations.md, references/cloud-sync/operations/known-gaps.md |
| Adoption constraints before committing | references/cloud-sync/adoption-checklist.md |
| Backend fit and alternatives | references/cloud-sync/onboarding/convex-vs-alternatives.md, references/cloud-sync/onboarding/why-convex-fits-swiftui.md |
| Live-data mental model | references/cloud-sync/onboarding/mental-model.md |
| Verified corrections and trust boundary | references/cloud-sync/operations/verified-corrections.md |
Cloud Sync Setup And Auth
| Decision | Read |
|---|---|
| Node and Convex CLI prerequisites | references/cloud-sync/setup-extra/node-prerequisites.md |
| Xcode SPM setup and ConvexMobile client init | references/cloud-sync/spm-setup.md, references/cloud-sync/client-surface.md |
First local npx convex dev run |
references/cloud-sync/setup-extra/first-run.md |
| Clerk account, JWT template, and Convex auth config | references/cloud-sync/setup-extra/clerk-jwt-template.md, references/cloud-sync/setup-extra/auth-config-wiring.md |
| Clerk-first Swift setup and root auth gate | references/cloud-sync/clerk-setup.md |
| Auth alternatives and custom provider fallback | references/cloud-sync/auth-custom-provider.md |
| Sign in with Apple, Keychain, and session restoration | references/cloud-sync/sign-in-with-apple.md |
| Backend ownership and authorization | references/cloud-sync/backend/auth-rules-and-server-ownership.md |
Cloud Sync SwiftUI, SDK, And Platform Behavior
Cloud Sync Pitfalls, Quick References, And Playbooks
Cloud-sync UI still obeys HIG and Liquid Glass rules: loading states use skeletons or tri-state UI, errors provide a specific retry path, auth UI lives in sheets/toolbars where appropriate, and sync status belongs in subtle chrome rather than content rows.
Workflow Routing
Use these only when the operation in the request is a whole-app workflow (bootstrap, audit, ship) rather than a single-view change.
| Need | Read |
|---|---|
| Bootstrap a new app end to end | references/workflow/bootstrap-new-app.md |
| Audit existing code with severity-tagged findings | references/workflow/audit-existing.md |
| Run final pre-release checks | references/workflow/ship-checklist.md |
Output Contract
Every session that uses this skill ends with a single report block. Do not pad it; do not omit it.
Report:
-
What changed: file paths plus one line per change. Group related edits.
-
Verification rung reached — claim the highest rung actually exercised, no more:
Rung Meaning 1 Read the code 2 Type-check or lint passes 3 Unit tests pass 4 Snapshot tests pass 5 Ran the program and observed the change 6 User confirmed the changed behavior -
What remains — only if anything remains. Be specific (file path, intended next rung, blocker).
Never claim done while the working tree is dirty, a guardrail in this skill is violated, or the stated verification rung was not actually reached. If a Liquid Glass change was made but never run on a macOS 26 device or simulator, claim Rung 2 — not Rung 5.