Guide SwiftUI development for macOS apps. Whether writing new code or reviewing existing code, apply deep understanding of SwiftUI's runtime behavior — how the observation registrar dispatches, how the attribute graph diffs view trees, how actor isolation interacts with view lifecycles.
How to Use
Writing code: Load relevant references before implementation. The patterns here prevent bugs that are expensive to find later — observation cascades, identity thrashing, concurrency overhead. When making architecture decisions (state ownership, view decomposition, AppKit bridging), consult the relevant reference for tradeoffs.
Reviewing code: Check each reference area systematically. Focus on genuine problems — observation inefficiencies, deprecated API, accessibility gaps, concurrency anti-patterns. Don't flag obvious issues or invent problems.
Partial scope: Load only what the task needs. Not every change requires all eight references.
References
| Reference |
Load when |
references/observation.md |
@Observable, @State, ForEach, data-driven views, Observations {} streams |
references/concurrency.md |
Task, async/await, actors, DispatchQueue, AsyncStream, scheduling decisions |
references/performance.md |
View composition, animations, gestures, large collections, Canvas, TimelineView |
references/views.md |
View decomposition, navigation, .task(id:), preference keys, custom Layout |
references/data.md |
State architecture, SwiftData, environment injection, bindings, persistence |
references/platform.md |
NSViewRepresentable, NSHostingView, multi-window, AppKit bridging, window chrome |
references/api.md |
API choice, deprecated patterns, modern Swift/SwiftUI idioms |
references/accessibility.md |
VoiceOver, keyboard navigation, Dynamic Type, Reduce Motion |
Principles
- Target macOS 26+, Swift 6.2 with strict concurrency and
@MainActor default isolation.
- Check whether the project enables
NonisolatedNonsendingByDefault (SE-0461) — this changes where nonisolated async functions execute. See references/concurrency.md.
- Prefer SwiftUI-native solutions. Use AppKit (
NSViewRepresentable, NSHostingView, NSWindow) only when SwiftUI has no equivalent.
- Understand the mechanism. When suggesting a pattern, know why it works — what the observation registrar does, what the attribute graph diffing costs, what
_modify vs set means for notification. Rules without understanding produce cargo-culted code.
- Do not introduce third-party frameworks without asking. Apple's open-source Swift packages (
swift-collections, swift-algorithms, swift-async-algorithms) are exceptions — prefer them over reimplementing non-trivial data structures or algorithms. See references/api.md.
Examples
User: "Review observation patterns in these sidebar views"
→ Load references/observation.md. Check each file for: state capture in ForEach, non-Equatable types on observed properties, missing @ObservationIgnored on caches, _modify vs set notification waste.
User: "I need to embed an NSCollectionView in SwiftUI"
→ Load references/platform.md. Apply NSViewRepresentable lifecycle, Equatable conformance for update gating, Coordinator for delegates.
User: "This view is re-rendering too much, help me debug it"
→ Load references/performance.md and references/observation.md. Check view identity (structural vs explicit), observation scope (are unrelated properties tracked in the same body?), @State vs @Observable for gesture-driven values.
Review Output
Organize findings by file. For each issue:
- File and relevant line(s).
- The pattern being violated and why it matters at the runtime level.
- Brief before/after code fix.
Skip clean files. End with a prioritized summary of the most impactful changes.
1---2name: swiftui-macos3description: Expert SwiftUI guidance for macOS apps — covers writing and reviewing code with runtime-level understanding of observation, concurrency, performance, and platform integration. Use when user asks to "build a SwiftUI view", "review my SwiftUI code", "fix observation issues", "bridge AppKit", "architect state management", "debug view updates", or works on any macOS SwiftUI project — building features, reviewing existing code, debugging view updates or performance, fixing concurrency issues, architecting state management, bridging AppKit, or making design decisions. Do NOT use for iOS/iPadOS-only SwiftUI, UIKit bridging, or basic Swift language questions. Focuses on non-obvious traps and deep patterns, not basics.4license: MIT5---67Guide SwiftUI development for macOS apps. Whether writing new code or reviewing existing code, apply deep understanding of SwiftUI's runtime behavior — how the observation registrar dispatches, how the attribute graph diffs view trees, how actor isolation interacts with view lifecycles.89## How to Use1011**Writing code**: Load relevant references before implementation. The patterns here prevent bugs that are expensive to find later — observation cascades, identity thrashing, concurrency overhead. When making architecture decisions (state ownership, view decomposition, AppKit bridging), consult the relevant reference for tradeoffs.1213**Reviewing code**: Check each reference area systematically. Focus on genuine problems — observation inefficiencies, deprecated API, accessibility gaps, concurrency anti-patterns. Don't flag obvious issues or invent problems.1415**Partial scope**: Load only what the task needs. Not every change requires all eight references.1617## References1819| Reference | Load when |20|---|---|21| `references/observation.md` | `@Observable`, `@State`, `ForEach`, data-driven views, `Observations {}` streams |22| `references/concurrency.md` | `Task`, `async`/`await`, actors, `DispatchQueue`, `AsyncStream`, scheduling decisions |23| `references/performance.md` | View composition, animations, gestures, large collections, `Canvas`, `TimelineView` |24| `references/views.md` | View decomposition, navigation, `.task(id:)`, preference keys, custom `Layout` |25| `references/data.md` | State architecture, SwiftData, environment injection, bindings, persistence |26| `references/platform.md` | `NSViewRepresentable`, `NSHostingView`, multi-window, AppKit bridging, window chrome |27| `references/api.md` | API choice, deprecated patterns, modern Swift/SwiftUI idioms |28| `references/accessibility.md` | VoiceOver, keyboard navigation, Dynamic Type, Reduce Motion |2930## Principles3132- Target **macOS 26+**, Swift 6.2 with strict concurrency and `@MainActor` default isolation.33- Check whether the project enables **`NonisolatedNonsendingByDefault`** (SE-0461) — this changes where `nonisolated` async functions execute. See `references/concurrency.md`.34- Prefer SwiftUI-native solutions. Use AppKit (`NSViewRepresentable`, `NSHostingView`, `NSWindow`) only when SwiftUI has no equivalent.35- **Understand the mechanism.** When suggesting a pattern, know *why* it works — what the observation registrar does, what the attribute graph diffing costs, what `_modify` vs `set` means for notification. Rules without understanding produce cargo-culted code.36- Do not introduce third-party frameworks without asking. Apple's open-source Swift packages (`swift-collections`, `swift-algorithms`, `swift-async-algorithms`) are exceptions — prefer them over reimplementing non-trivial data structures or algorithms. See `references/api.md`.3738## Examples3940**User**: "Review observation patterns in these sidebar views"41→ Load `references/observation.md`. Check each file for: state capture in ForEach, non-Equatable types on observed properties, missing `@ObservationIgnored` on caches, `_modify` vs `set` notification waste.4243**User**: "I need to embed an NSCollectionView in SwiftUI"44→ Load `references/platform.md`. Apply `NSViewRepresentable` lifecycle, `Equatable` conformance for update gating, `Coordinator` for delegates.4546**User**: "This view is re-rendering too much, help me debug it"47→ Load `references/performance.md` and `references/observation.md`. Check view identity (structural vs explicit), observation scope (are unrelated properties tracked in the same body?), `@State` vs `@Observable` for gesture-driven values.4849## Review Output5051Organize findings by file. For each issue:52531. File and relevant line(s).542. The pattern being violated and *why it matters* at the runtime level.553. Brief before/after code fix.5657Skip clean files. End with a prioritized summary of the most impactful changes.
Lord1Egypt