---
name: swiftui-expert
description: This skill should be used when the user is building, reviewing, or debugging SwiftUI views and apps. Detects iOS and Swift version from the project. Covers creating views, state management with @Observable, NavigationStack routing, animations, accessibility, performance optimization, Liquid Glass adoption, design systems, and clean code architecture. Use when the user asks things like "create a SwiftUI list view", "my @State isn't updating", "add navigation to my app", "make this accessible", "optimize SwiftUI performance", "add Liquid Glass to my toolbar", "fix my Swift concurrency warning", "set up SwiftData models", "critique my SwiftUI code", "fix my SwiftUI layout", "create a custom ViewModifier", or "add Dark Mode support".
---

# SwiftUI Expert

Provide expert guidance on SwiftUI development. Detect the project's deployment target and Swift version from `Package.swift`, `.xcodeproj`, or project settings and adapt guidance accordingly. Apply modern API usage, clean code principles, design craft, accessibility, and performance best practices. Do not invent APIs — if unsure, say so.

## Core Principles

- Target the latest stable iOS and Swift unless the project specifies otherwise. Check the deployment target before suggesting version-gated APIs.
- Prefer SwiftUI-native solutions. Avoid UIKit unless explicitly needed or for gaps SwiftUI cannot fill.
- Do not introduce third-party frameworks without asking first.
- Each type (struct, class, enum) belongs in its own file. Flag files with multiple type definitions.
- Use a feature-based folder structure, not layer-based (no "ViewModels/" folder).
- Code must adhere to Apple's Human Interface Guidelines.

## Modern API — Always Use

Replace deprecated API immediately. See `references/modern-api.md` for the complete table.

Key replacements:
- `foregroundStyle()` not `foregroundColor()`
- `clipShape(.rect(cornerRadius:))` not `cornerRadius()`
- `NavigationStack` / `NavigationSplitView` not `NavigationView`
- `@Observable` not `ObservableObject` / `@Published` / `@StateObject` / `@ObservedObject`
- `navigationDestination(for:)` not `NavigationLink(destination:)`
- `Tab` API not `tabItem()`
- `sensoryFeedback()` not UIKit haptics
- `#Preview` not `PreviewProvider`
- `containerRelativeFrame()` or `visualEffect()` not `GeometryReader` (when possible)
- `Task.sleep(for:)` not `Task.sleep(nanoseconds:)`
- `@Entry` macro for custom environment/focus/transaction keys

## State Management

- `@State` must be `private`. It is owned by the view that creates it.
- `@Observable` classes must be `@MainActor` (unless the project uses default MainActor isolation).
- Use `@State` for ownership of `@Observable` objects, `@Bindable` for bindings to them, `@Environment` for passing them.
- Never use `@AppStorage` inside `@Observable` classes — it will not trigger view updates.
- Never create `Binding(get:set:)` in body — use `@State` + `onChange()`.
- Nested `@Observable` works fine. Nested `ObservableObject` does not propagate changes.
- For `@Observable` classes, mark properties you don't want tracked with `@ObservationIgnored`.

See `references/state-data.md` for property wrapper decision flowchart and SwiftData rules.

## View Composition & Clean Code

- Strongly prefer extracting subviews into separate `View` structs over computed properties or methods returning `some View`. Computed properties get no re-evaluation isolation from `@Observable` — separate structs allow SwiftUI to skip unchanged subviews entirely.
- Keep `body` short and computation-free. No sorting, filtering, or formatter creation in `body`.
- Extract button actions into methods. No inline business logic in `task()`, `onAppear()`, or `body`.
- Apply DRY: repeated styling → `ViewModifier`. Repeated layout → extracted `View`. Repeated logic → model/service method.
- Apply Single Responsibility: each view does one thing. Each model owns one domain. Each file contains one type.
- Apply Open/Closed: extend behavior through protocols and extensions, not by modifying existing types. Use `ViewModifier` + `View` extension for reusable styling.
- Prefer `overlay`/`background` for decoration; `ZStack` for peer composition.
- Container views: use `@ViewBuilder let content: Content` (not stored closures).

See `references/view-composition.md` for patterns, ordering conventions, and anti-patterns.

## Design Craft

- Establish a clear visual direction — commit to an aesthetic, don't mix styles.
- Avoid generic AI aesthetics: no cards for everything, no gratuitous gradients/materials/shadows, no bouncy animations everywhere, no web-style CTA buttons. Use native iOS components. Apply the squint test — hierarchy should be visible even blurred.
- Define design tokens (colors, typography, spacing, corner radii, animation timings) in a shared constants enum. One source of truth.
- Follow the 60-30-10 color rule: 60% dominant neutral, 30% secondary, 10% accent.
- Use semantic color names for role, not RGB. Support dark mode with system colors or asset catalog.
- Establish clear typographic hierarchy: 3-4 levels max. Use weight contrast more than size contrast.
- Use Dynamic Type fonts exclusively. Never hardcode `.font(.system(size:))`.
- Minimum 44x44pt tap targets. Handle all interaction states (default, pressed, disabled, loading, error, success).
- Write clear UX copy: verb-based button labels, actionable error messages, helpful empty states.

See `references/design-craft.md` for visual hierarchy, color harmony, typography pairing, interaction states, spacing tokens, UX writing, and HIG alignment.

## Animation & Motion

- Use `withAnimation { }` (explicit) for control. Use `.animation(_:value:)` for implicit — always with a `value:` parameter.
- Prefer GPU-friendly transforms (`offset`, `scale`, `rotation`) over layout changes (`frame`).
- Use `@Animatable` macro (iOS 26+) not manual `animatableData`.
- Chain animations via `withAnimation` completion closures, not delays.
- `matchedGeometryEffect` with `@Namespace` for hero transitions.
- Respect `accessibilityReduceMotion` — replace motion with opacity.
- Spring animations for natural feel. `.bouncy` for playful, `.smooth` for subtle.

See `references/animation.md` for phase/keyframe animators, transitions, and Liquid Glass morphing.

## Accessibility

- VoiceOver: every interactive element needs a text label. `Button("Add", systemImage: "plus", action:)` not icon-only.
- Use `Image(decorative:)` or `accessibilityHidden()` for decorative images.
- Never use `onTapGesture()` when `Button` works. If you must, add `.accessibilityAddTraits(.isButton)`.
- Respect `accessibilityDifferentiateWithoutColor` — don't rely on color alone.
- Use `accessibilityInputLabels()` for complex/changing button labels.
- Test with VoiceOver and Accessibility Inspector.

See `references/accessibility.md` for Dynamic Type, element grouping, custom controls, and charts accessibility.

## Performance

- Ternary expressions over `if/else` view branching (avoids `_ConditionalContent`).
- No `AnyView`. Use `@ViewBuilder`, `Group`, or generics.
- Fine-grained `@Observable` models — avoid broad dependencies on arrays.
- Use `LazyVStack`/`LazyHStack` for large data sets.
- `task()` over `onAppear()` for async (auto-cancellation).
- Keep view initializers trivial. Defer work to `task()`.
- Debug with `Self._printChanges()` and random background colors.

See `references/performance.md` for the full code smell catalog and remediation patterns.

## Concurrency

- Always `async`/`await` over closures. Never use GCD (`DispatchQueue`).
- `@MainActor` on `@Observable` classes (if not using default MainActor isolation).
- Use `.task` modifier for async work in views.
- Prefer `Task` over `Task.detached` (inherits actor context).
- Flag unprotected mutable shared state.
- Assume strict concurrency. Flag `@Sendable` violations.

See `references/concurrency.md` for actor patterns, Sendable, and Swift 6 migration.

## Navigation & Presentation

- `NavigationStack` with `navigationDestination(for:)`. Never mix with `NavigationLink(destination:)`.
- `sheet(item:)` over `sheet(isPresented:)` for optional data.
- Attach `confirmationDialog()` to its trigger (for Liquid Glass animations).
- Single "OK" alert buttons can be omitted.
- `TabView(selection:)` binds to an enum, not Int/String.

See `references/navigation.md` for split views, inspector patterns, and deep links.

## Liquid Glass (iOS 26+)

- Recompile with Xcode 26 for automatic adoption on NavigationBar, TabBar, Toolbar.
- Apply `.glassEffect()` **after** layout and visual modifiers.
- Use `GlassEffectContainer` when multiple glass elements coexist.
- `.interactive()` only on tappable/focusable elements.
- `.buttonStyle(.glass)` / `.buttonStyle(.glassProminent)` for actions.
- Gate with `#available(iOS 26, *)` and provide `.ultraThinMaterial` fallback.

See `references/liquid-glass.md` for morphing transitions, design system notes, and scroll edge effects.