appkit-architect
Architect-level macOS-native design — AppKit versus SwiftUI for desktop, window and menu architecture, document-based apps and NSDocument, sandboxing and entitlements, Mac App Store versus direct distribution, and the macOS conventions users expect. Use when the app must feel native on macOS.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- appkit-architect
- license
- MIT
- metadata
- { "crusor-path": "desktop-architect/runtimes-architect/appkit-architect", "crusor-domain": "desktop-architect", "crusor-origin": "original", "crusor-sources": "developer.apple.com/documentation/appkit; developer.apple.com/documentation/swiftui; developer.apple.com/documentation/security/app_sandbox", "crusor-triggers": "appkit, macos app, nsdocument, mac app sandbox, mac catalyst, app store mac, menu bar app, notarization mac, mac app, macos, menu bar, menubar app", "crusor-verified-on": "2026-10-30" }
- description
- Architect-level macOS-native design — AppKit versus SwiftUI for desktop, window and menu architecture, document-based apps and NSDocument, sandboxing and entitlements, Mac App Store versus direct distribution, and the macOS conventions users expect. Use when the app must feel native on macOS.
- compatibility
- AppKit, SwiftUI on macOS, Swift, notarisation
03 SKILL.md 正文
AppKit / macOS Architect
A macOS app is judged on menus, windows, and sandbox behaviour. Users do not forgive a Mac app that behaves like a website in a frame.
When to use
- A native Mac experience is the product (pro apps, developer tools, utilities).
- Deep system integration: services, drag and drop, menu bar, document handling.
- App Store or notarised direct distribution.
When NOT to use
- The same UI must ship on Windows/Linux → Electron/Tauri first.
- A thin client where a web app suffices.
Decision 1 — AppKit or SwiftUI
| Need | Choice |
|---|---|
| new app, mostly standard UI | SwiftUI, AppKit where it falls short |
| document-based, complex window management | AppKit with SwiftUI views inside |
| menu bar utility | SwiftUI MenuBarExtra or AppKit status item |
| pro app with custom canvases | AppKit + Metal/SceneKit |
- SwiftUI on macOS still lacks mature equivalents for some AppKit patterns; use
NSViewRepresentabledeliberately rather than fighting the framework. - One navigation model: sidebar/split view, not a pile of windows.
Decision 2 — macOS conventions
- Menu bar with the standard menus and keyboard shortcuts; a Mac app without a proper menu feels foreign.
- Preferences via
Settingsscene/NSWindowController, not a custom modal. - Window state restoration; users expect the app to reopen where they left it.
- Drag and drop, Quick Look, Services, and keyboard navigation where applicable.
Decision 3 — Documents
NSDocument/ReferenceFileDocumentfor document-based apps — undo, autosave, and versions come almost free.- iCloud Drive or a user-chosen folder; the sandbox restricts arbitrary paths.
- Autosave and version browsing are expected behaviours in a document app.
Decision 4 — Sandbox and entitlements
- App Sandbox required for the App Store; strongly recommended for direct distribution.
- Entitlements are per capability: file access (user-selected), network client, printing, camera.
- Security-scoped bookmarks for persistent access outside the container.
- Hardened runtime + notarisation for direct distribution; check Gatekeeper on a clean machine.
Decision 5 — Distribution
- App Store: sandbox, review, 30% (or reduced rate), no self-update.
- Direct: notarised DMG, Sparkle-style update, licence handling you own.
- Both: one codebase, capability detection at build time; keep the differences in a thin layer.
Failure modes at scale
- No menu bar; keyboard shortcuts absent, users assume the app is broken.
- Sandbox enabled late; file access patterns need a redesign.
- Custom window chrome with broken full-screen and Split View.
- Sparkle updates without signature verification.
- App Store build shipped without sandbox, rejected after weeks.
Verification receipts
- Framework split documented: SwiftUI screens, AppKit integrations.
- Menu bar and shortcut inventory matching macOS conventions.
- Sandbox entitlements list with the feature each enables.
- Notarised build launched on a clean machine.
- Window restoration and document autosave tested.
04 同仓库更多 Skills
interaction-patterns-architect
Architect-level interaction design in code — choosing established patterns over invented ones, feedback and latency behaviour, destructive-action safeguards, navigation and overlay conventions, and the state model behind every interactive surface. Use when a screen has to behave, not just look.
design-system-ops-architect
Architect-level operation of a design system in code — token pipelines and versioning, component API and variant policy, the catalogue as the contract, adoption metrics, and the governance that stops a system from forking into three. Use when a component library must survive several teams.
design-handoff-architect
Architect-level design handoff — what must be specified before implementation starts, tokens over raw values, responsive and content-limit contracts, state matrices, and the review loop that catches drift between design and code. Use when a design is about to become code.
content-microcopy-architect
Architect-level UI content — where strings live, voice and terminology consistency, error and empty-state copy as part of the interface, translation-ready authoring, and the content model a product needs before it multiplies screens. Use when the words in the interface matter as much as the pixels.
ui-ux-implementation-architect
Architect-level direction for turning a design into working UI — the handoff contract, component ownership versus screen-level layout, interaction and state conventions, design QA gates, and the review habits that keep an implementation faithful without frozen pixels. Use before any specific UI implementation skill.
test-strategy-architect
Architect-level test strategy — allocating assertions across unit, integration, contract and end-to-end layers, designing for testability through dependency boundaries, fixture and data strategy, and the flake and coverage policies that keep a suite trustworthy. Use when defining how a codebase is tested.