{"skill":{"slug":"swiftui-macos","displayName":"SwiftUI macOS","summary":"Expert SwiftUI guidance for macOS apps — covers writing and reviewing code with runtime-level understanding of observation, concurrency, performance, and pla...","description":"---\nname: swiftui-macos\ndescription: 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.\nlicense: MIT\ncompatibility: Requires macOS 26+ targeting and Swift 6.2 with strict concurrency. Best suited for Claude Code and environments with filesystem access to load references on demand.\nmetadata:\n  author: kageroumado\n  version: 1.0.0\n---\n\nGuide 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.\n\n## How to Use\n\n**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.\n\n**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.\n\n**Partial scope**: Load only what the task needs. Not every change requires all eight references.\n\n## References\n\n| Reference | Load when |\n|---|---|\n| `references/observation.md` | `@Observable`, `@State`, `ForEach`, data-driven views, `Observations {}` streams |\n| `references/concurrency.md` | `Task`, `async`/`await`, actors, `DispatchQueue`, `AsyncStream`, scheduling decisions |\n| `references/performance.md` | View composition, animations, gestures, large collections, `Canvas`, `TimelineView` |\n| `references/views.md` | View decomposition, navigation, `.task(id:)`, preference keys, custom `Layout` |\n| `references/data.md` | State architecture, SwiftData, environment injection, bindings, persistence |\n| `references/platform.md` | `NSViewRepresentable`, `NSHostingView`, multi-window, AppKit bridging, window chrome |\n| `references/api.md` | API choice, deprecated patterns, modern Swift/SwiftUI idioms |\n| `references/accessibility.md` | VoiceOver, keyboard navigation, Dynamic Type, Reduce Motion |\n\n## Principles\n\n- Target **macOS 26+**, Swift 6.2 with strict concurrency and `@MainActor` default isolation.\n- Check whether the project enables **`NonisolatedNonsendingByDefault`** (SE-0461) — this changes where `nonisolated` async functions execute. See `references/concurrency.md`.\n- Prefer SwiftUI-native solutions. Use AppKit (`NSViewRepresentable`, `NSHostingView`, `NSWindow`) only when SwiftUI has no equivalent.\n- **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.\n- 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`.\n\n## Examples\n\n**User**: \"Review observation patterns in these sidebar views\"\n→ 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.\n\n**User**: \"I need to embed an NSCollectionView in SwiftUI\"\n→ Load `references/platform.md`. Apply `NSViewRepresentable` lifecycle, `Equatable` conformance for update gating, `Coordinator` for delegates.\n\n**User**: \"This view is re-rendering too much, help me debug it\"\n→ 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.\n\n## Review Output\n\nOrganize findings by file. For each issue:\n\n1. File and relevant line(s).\n2. The pattern being violated and *why it matters* at the runtime level.\n3. Brief before/after code fix.\n\nSkip clean files. End with a prioritized summary of the most impactful changes.\n","tags":{"appkit":"1.0.0","apple":"1.0.0","concurrency":"1.0.0","latest":"1.0.0","macos":"1.0.0","observation":"1.0.0","swift":"1.0.0","swiftui":"1.0.0"},"stats":{"comments":0,"downloads":594,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1773280055380,"updatedAt":1778491843876},"latestVersion":{"version":"1.0.0","createdAt":1773280055380,"changelog":"Runtime-level SwiftUI guidance for macOS apps — observation internals, concurrency scheduling hierarchy, view identity, AppKit bridging. Built from developing Refrax browser with SwiftUI.","license":"MIT-0"},"metadata":null,"owner":{"handle":"kageroumado","userId":"s171qn3wpj3zdzrbkg7gra9vyn8857pg","displayName":"陽炎窓","image":"https://avatars.githubusercontent.com/u/262214232?v=4"},"moderation":null}