swiftui-expert

name	swiftui-expert
description	Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, accessibility, and modern APIs. Use when building SwiftUI features, refactoring views, reviewing code quality, or adopting modern SwiftUI patterns.
metadata	{"version":"2.1.0","author":"SwiftyJourney","tags":["swiftui","ios","apple","state-management","view-composition","performance","animations","accessibility","liquid-glass","swift"]}

SwiftUI Expert Skill

Agent Behavior Contract

When this skill is active, follow these rules strictly:

1. Focus on facts and best practices, not architecture — defer architectural decisions (MVVM, MVC, VIPER, Clean Architecture, Coordinator) to ios-architecture-expert.
2. Always prefer @Observable over ObservableObject for new code. Mark @Observable classes with @MainActor unless using default actor isolation.
3. Never use applyIf or generic conditional modifier helpers — they break view identity.
4. Prefer modifiers over conditional views for state changes (preserves structural identity).
5. Use modern APIs over deprecated equivalents — see references/modern-apis.md.
6. Lead with corrected/improved code when reviewing; explain why a pattern is better (diffing, thread safety, API correctness).
7. Use "prefer"/"avoid" for recommendations; "always"/"never" only for API correctness.
8. Respond in the same language the user writes in — default to English when uncertain.
9. Adopt Liquid Glass only when explicitly requested — glass is for controls and navigation only (HIG).
10. Gate iOS 26+ features with #available and provide fallbacks.

---

Diagnostic Table

Symptom	First check	Smallest fix	Deep dive
Wrong property wrapper chosen	Ownership direction	Match wrapper to data flow	references/state-management.md
View re-renders too often	Dependency graph	Narrow state dependencies	references/performance-patterns.md
Deprecated API warning	API replacement table	Swap to modern equivalent	references/modern-apis.md
View body is 200+ lines	View extraction rules	Extract struct subviews	references/view-composition.md
ForEach flickers or reorders	Identity stability	Use stable Identifiable ID	references/list-patterns.md
Animation is janky or missing	Implicit vs explicit	Match animation to state change site	references/animation-basics.md
Glass effect on wrong layer	HIG compliance	Glass on controls only, not content	references/liquid-glass.md
Custom control lacks accessibility	Semantic components	Use Button/Label or accessibilityRepresentation	references/accessibility-patterns.md
Tap/gesture not firing inside a scroll or list	Gesture precedence	Use highPriorityGesture/simultaneousGesture	references/gestures.md
Async load leaks, re-fires, or janks the UI	Task lifecycle & isolation	.task/.task(id:); offload heavy work with @concurrent	references/data-loading-and-tasks.md
Need a layout stacks/grids can't express	Layout negotiation	Conform to the Layout protocol	references/layout-protocol.md
App body won't compile or state leaks across windows	Scene structure	App body returns some Scene; WindowGroup is per-window	references/app-lifecycle-and-scenes.md
Persisting settings or restoring per-scene state	Persistence mechanism	@AppStorage/@SceneStorage/SwiftData/PreferenceKey	references/data-persistence.md

---

Quick Summary

Area	Key Principle	Reference
State Management	@Observable + @MainActor; @State for owned, @Binding for child-modifies-parent	references/state-management.md
View Composition	Small single-responsibility views; extract structs, not @ViewBuilder functions	references/view-composition.md
Modern APIs	foregroundStyle, clipShape, NavigationStack, Tab, Button over onTapGesture	references/modern-apis.md
Performance	Cheap inits, pure body, narrow dependencies, stable ForEach identity	references/performance-patterns.md
Animations	withAnimation for events, .animation(_:value:) for reactive, transforms over layout	references/animation-basics.md
Accessibility	Semantic fonts/styles, @ScaledMetric, accessibilityRepresentation for custom controls	references/accessibility-patterns.md
Liquid Glass	Controls/navigation only (HIG); Glass.regular default; GlassEffectContainer for groups	references/liquid-glass.md
Data Loading	.task over .onAppear{Task{}}; .task(id:) for fetch-on-change; @concurrent to offload heavy work	references/data-loading-and-tasks.md
Gestures	@GestureState auto-reset; gesture precedence (highPriority/simultaneous); modern MagnifyGesture/RotateGesture	references/gestures.md
Layout	Parent proposes, child chooses, parent positions; custom Layout for bespoke arrangements	references/layout-protocol.md
App Lifecycle	App body returns some Scene; WindowGroup per-window state; scenePhase read-site semantics	references/app-lifecycle-and-scenes.md
Persistence	@AppStorage (global), @SceneStorage (per-scene), SwiftData wiring, PreferenceKey (child→parent)	references/data-persistence.md

---

Quick Reference

Property Wrapper Selection

Wrapper	Use When
@State	Internal view state (must be private), or owned @Observable class
@Binding	Child modifies parent's state
@Bindable	Injected @Observable needing bindings
let	Read-only value from parent
var	Read-only value watched via .onChange()

Full guide including legacy wrappers: state-management.md

Modern API Replacements

Deprecated	Modern Alternative
foregroundColor()	foregroundStyle()
cornerRadius()	clipShape(.rect(cornerRadius:))
tabItem()	Tab API (iOS 18+)
onTapGesture()	Button (unless need location/count)
NavigationView	NavigationStack
onChange(of:) { value in }	onChange(of:) { old, new in } or onChange(of:) { }
GeometryReader	containerRelativeFrame() or visualEffect()
MagnificationGesture	MagnifyGesture
RotationGesture	RotateGesture

Full table: modern-apis.md

---

Workflow Decision Tree

1) Review existing SwiftUI code

• Check property wrapper usage -> references/state-management.md
• Verify modern API usage -> references/modern-apis.md
• Verify view composition and extraction -> references/view-composition.md
• Check performance patterns -> references/performance-patterns.md
• Inspect accessibility and Liquid Glass -> references/accessibility-patterns.md, references/liquid-glass.md

2) Improve existing SwiftUI code

• Audit state management (prefer @Observable over ObservableObject) -> references/state-management.md
• Replace deprecated APIs -> references/modern-apis.md
• Extract complex views into subviews -> references/view-composition.md
• Optimize hot paths and list identity -> references/performance-patterns.md, references/list-patterns.md
• Improve animations and accessibility -> references/animation-basics.md, references/accessibility-patterns.md

3) Implement new SwiftUI feature

• Design data flow first: owned vs injected state -> references/state-management.md
• Use modern APIs and @Observable -> references/modern-apis.md
• Structure views for optimal diffing -> references/view-composition.md
• Apply correct animation patterns -> references/animation-basics.md, references/animation-advanced.md
• Add accessibility and glass effects (if requested) -> references/accessibility-patterns.md, references/liquid-glass.md

---

Guardrails

• Do not enforce specific architectures (MVVM, MVC, VIPER) — defer to ios-architecture-expert
• Do not use applyIf or conditional modifier helpers that break view identity
• Do not declare passed values as @State or @StateObject — they only accept initial values
• Do not create objects or start Tasks in view initializers or body
• Do not use .indices for ForEach identity with dynamic content
• Do not apply glass effects to content layer views — glass is for controls and navigation only (HIG)
• Do not use AnyView in list rows
• Do not use GeometryReader when containerRelativeFrame(), onGeometryChange, or visualEffect suffice

---

Verification Checklist

When implementing or reviewing SwiftUI code:

1. Property wrappers match ownership direction (@State private, @Binding for modification, @Observable for shared)
2. No deprecated APIs (foregroundColor, cornerRadius, NavigationView, tabItem)
3. View body is pure — no side effects, no Task creation, no object allocation
4. Complex views extracted into struct subviews (not @ViewBuilder functions)
5. ForEach uses stable Identifiable identity (never .indices)
6. Animations use value parameter or withAnimation (no deprecated parameterless .animation())
7. Accessibility: semantic fonts, @ScaledMetric, Button over onTapGesture
8. Liquid Glass (if present): #available gated, controls-only, GlassEffectContainer for groups
9. No applyIf, no conditional modifier helpers, no if/else for style changes
10. Views work in any context (no hardcoded sizes, no UIScreen.main.bounds)

---

Reference Router

Open the smallest reference that matches the question:

• State & Data Flow
  • state-management.md — property wrappers, data flow, when to use a ViewModel
  • data-persistence.md — @AppStorage, @SceneStorage, SwiftData wiring, PreferenceKey
  • data-loading-and-tasks.md — .task/.task(id:) entry points, @concurrent offloading, cancellation
• View Structure & Layout
  • view-composition.md — view extraction, styles, specialized views, reusability
  • list-patterns.md — ForEach identity, stability, list best practices
  • layout-protocol.md — layout negotiation, custom Layout, alignment guides
• Modern APIs & Navigation
  • modern-apis.md — modern API usage and deprecated replacements
  • navigation-patterns.md — NavigationStack, deep linking, programmatic navigation
  • scroll-patterns.md — ScrollView patterns and programmatic scrolling
  • text-formatting.md — modern text formatting and string operations
• App Structure
  • app-lifecycle-and-scenes.md — App protocol, scenes, WindowGroup, scenePhase
• Performance & Optimization
  • performance-patterns.md — optimization techniques and anti-patterns
  • image-optimization.md — AsyncImage, image downsampling
• Animation & Interaction
  • animation-basics.md — core concepts, implicit/explicit animations
  • animation-transitions.md — transitions, custom transitions, Animatable
  • animation-advanced.md — transactions, phase/keyframe, completion handlers
  • gestures.md — gesture types, @GestureState, composition & precedence
• Accessibility & Platform
  • accessibility-patterns.md — semantic styling, adaptive spacing, VoiceOver
  • liquid-glass.md — iOS 26+ Liquid Glass API and HIG guidance