AGENT SKILL

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 NSViewRepresentable deliberately 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 Settings scene/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/ReferenceFileDocument for 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

  1. Framework split documented: SwiftUI screens, AppKit integrations.
  2. Menu bar and shortcut inventory matching macOS conventions.
  3. Sandbox entitlements list with the feature each enables.
  4. Notarised build launched on a clean machine.
  5. Window restoration and document autosave tested.

04 同仓库更多 Skills

SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

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.

★ 0