---
name: apple-swiftui-patterns
description: "Build or refactor SwiftUI presentation, state ownership, navigation, windowing, and AppKit interop. Use for native Apple UI structure and availability-gated platform features such as Liquid Glass."
---

# Apple SwiftUI Patterns

## Purpose

Use this skill when the task is UI structure, view refactoring, platform fit, or Apple 27 SwiftUI adoption. Keep the app native: Swift, SwiftUI, AppKit where necessary, WatchKit-adjacent patterns where relevant, and platform-specific behavior behind small interfaces.

## Workflow

1. Identify the platform and surface.
   - macOS window, menu, settings, toolbar, command, inspector, or AppKit bridge
   - iOS/iPadOS navigation, tab, sheet, list, form, toolbar, search, focus, media, or haptics
   - watchOS glanceable flow, widget/control handoff, or companion-app surface
   - cross-platform SwiftUI view, state owner, model adapter, or preview

2. Place state and logic with their owners.
   - Keep business logic outside view bodies.
   - Use Observation and explicit state ownership where it reduces invalidation and unclear data flow.
   - Add a seam for present variation, proof, lifecycle ownership, or platform isolation; adapter count alone does not justify it.
   - Prefer platform conditionals at narrow edges instead of mixing incompatible UI assumptions in one view.

3. Adopt Apple 27 UI affordances where they earn their keep.
   - Prefer native tab, toolbar, split-view, search, sheet, popover, window, command, settings, and inspector APIs before custom chrome.
   - Treat Liquid Glass as a cross-platform, availability-gated enhancement for system-aligned surfaces, not a generic decoration layer.
   - Start with standard components and their system styling; add sparse custom glass only when it improves a specific hierarchy or interaction.
   - Use `GlassEffectContainer` only when grouped glass effects or interactions need coordination, or when measured rendering efficiency justifies it.
   - Use Icon Composer 2 only for app/icon work that needs layered Liquid Glass assets.

4. Refactor views deliberately.
   - Split large views around state ownership, repeated subcomponents, platform variants, or testable interactions.
   - Move files when ownership changes, not for tidiness alone.
   - Update previews when they are useful for the edited surface.

5. Prove behavior.
   - Build through `apple-build-run-debug`.
   - Use previews, screenshots, simulator/browser proof, or macOS launch proof when visual behavior matters.
   - Use `apple-performance-memory` if the concern is jank, body churn, layout cost, or memory growth.

## References

Use only the references needed for the current platform and component:

- `references/ios/`
- `references/macos/`
- `references/appkit/`
- `references/window-management/api-snippets.md`
- `references/liquid-glass.md`