/swiftui-max

name: swiftui-max
description: Expert SwiftUI guidance for building UI on iOS, iPadOS, macOS, watchOS, tvOS, and visionOS. Use whenever writing, reviewing, refactoring, or debugging ANY SwiftUI code — views, view modifiers, layout, navigation (NavigationStack/SplitView, deep links), lists and scrolling, animation and transitions, state management (@State, @Binding, @Observable, Observation, environment), Liquid Glass adoption, toolbars, sheets and presentations, widgets/Live Activities, UIKit/AppKit interop, or SwiftUI performance problems (slow lists, hitches, excessive view updates). ALSO use it when building common UI components (bottom sheets, tab bars, onboarding, infinite scroll, skeletons, charts, forms, toasts), choosing or adding UI libraries (Pow, Lottie, Nuke, Kingfisher, snapshot testing, Inject hot reload, TCA), building a design system (tokens, themes, component packages), or iterating visually (simulator screenshots, previews, snapshot tests). Trigger on mentions of SwiftUI, "build a screen/view", "make it look good", @Observable, ObservableObject migration, NavigationView, glassEffect, WidgetKit, or any *View struct with a body. For pure Swift language/concurrency questions, the sibling swift-language skill applies instead.

SwiftUI to the Max

Write SwiftUI the way a senior Apple-platforms engineer writes it in mid-2026: Observation-first, value-typed, identity-aware, and Liquid Glass-native. Prefer deleting code to adding it; most SwiftUI bugs are self-inflicted state or identity problems.

**Scope split**: This skill owns UI. Swift language, strict concurrency, actors/Sendable, macros, SwiftPM, and Swift Testing belong to the sibling **swift-language** skill — route there instead of answering language questions here (e.g. "is this Sendable", Swift 6 migration, `@concurrent`). SwiftUI code that *contains* concurrency needs both.

Give yourself eyes (mandatory for UI work)

UI built blind is the single biggest quality gap in agent-written SwiftUI. Never declare UI work done without having rendered and *looked at* it. The loop:

1. Build for the simulator (`xcodebuild -scheme App -destination 'platform=iOS Simulator,name=iPhone 17' build`) or, for isolated components, render with `ImageRenderer` from a scratch target. 2. Screenshot: `xcrun simctl io booted screenshot /tmp/screen.png` — then **read the image** and critique it against `apple-hig-ux` standards (spacing, hierarchy, Dynamic Type, dark mode). 3. Repeat across the matrix that matters: light/dark, small/large Dynamic Type, smallest + largest supported device. 4. Lock in what's right with snapshot tests so regressions are caught without eyes.

Full workflow (simulator CLI, PreviewHost pattern, hot reload with Inject, snapshot testing, accessibility audits): `references/visual-iteration-workflow.md`.

Build vs. recipe vs. library

Before hand-rolling any common component, check `references/component-recipes.md` (canonical implementations of the 12 hardest-to-get-right components) and `references/ecosystem-libraries.md` (curated, maintenance-verified third-party catalog: effects, images, markdown, dev tooling, architecture). Default order: native API → recipe from this skill → library from the vetted list. Never re-implement what Pow/Nuke/Lottie already do well; never import a library for what native does in 20 lines. For app-wide consistency (tokens, themes, reusable components), follow `references/design-system-kit.md` and consume tokens instead of magic numbers.

Version landscape (July 2026)

| Release | Status | Headline UI features | |---|---|---| | iOS 17 / macOS 14 | old floor | Observation (`@Observable`), `@Entry`-era environment patterns, scrollTargetBehavior/scrollPosition, keyframe/phase animators, `#Preview` | | iOS 18 / macOS 15 | common floor | `@Entry` macro, zoom navigation transitions, scroll geometry/visibility callbacks, mesh gradients, floating tab bar/`TabSection` | | iOS 26 / macOS 26 "Tahoe" | **current shipping** (unified "26" version number across platforms) | **Liquid Glass** design system (`glassEffect`, `GlassEffectContainer`), `@Animatable` macro, rich-text `TextEditor` (AttributedString), `WebView`, scroll edge effects, `tabBarMinimizeBehavior`, Instruments SwiftUI template | | iOS 27 / macOS 27 "Golden Gate" (WWDC26) | **beta** — mark all usage as beta | `@State` becomes a macro (lazy class init), reorderable containers, `swipeActions` in any ScrollView, `ToolbarOverflowMenu`/`visibilityPriority`, `WritableDocument`/`ReadableDocument`, `AsyncImage` HTTP caching, `ContentBuilder` (build-time wins), item-binding `alert`/`confirmationDialog`, resizable iPhone apps |

Gate anything above the deployment target with `#available` and provide a real fallback, not a blank view.

Modern defaults (non-negotiable unless the target forces otherwise)

1. **Observation over Combine-era state.** New model types are `@Observable` classes (or plain structs held in `@State`). `ObservableObject`/`@Published`/`@StateObject` are legacy — use only below iOS 17. Why: Observation tracks per-property reads, so views update only when a property they actually read changes. 2. **`NavigationStack` / `NavigationSplitView`, never `NavigationView`.** Drive navigation with a `path` value (`NavigationPath` or a typed array) so deep links and state restoration are data, not view spelunking. 3. **`@Entry` for environment keys.** One line replaces the `EnvironmentKey` + extension boilerplate:

   extension EnvironmentValues {
       @Entry var audioMixer = AudioMixer()   // iOS 18+; hand-rolled key below that
   }

4. **Composition over `AnyView`.** Return `some View`, split subviews, use `@ViewBuilder` properties/functions and generics. `AnyView` erases identity and blocks diffing — reach for it only at true dynamic boundaries (e.g. heterogeneous routing tables). 5. **Stable identity.** `ForEach` over `Identifiable` data with ids that survive edits (never `id: \.self` on mutable st