Swiftui Expert Skill

1---
2name: swiftui-expert-skill
3description: Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns.
4---
5 
6# SwiftUI Expert Skill
7 
8## Overview
9Use this skill to build, review, or improve SwiftUI features with correct state management, modern API usage, Swift concurrency best practices, optimal view composition, and iOS 26+ Liquid Glass styling. Prioritize native APIs, Apple design guidance, and performance-conscious patterns. This skill focuses on facts and best practices without enforcing specific architectural patterns.
10 
11## Workflow Decision Tree
12 
13### 1) Review existing SwiftUI code
14- Check property wrapper usage against the selection guide (see `references/state-management.md`)
15- Verify modern API usage (see `references/modern-apis.md`)
16- Verify view composition follows extraction rules (see `references/view-structure.md`)
17- Check performance patterns are applied (see `references/performance-patterns.md`)
18- Verify list patterns use stable identity (see `references/list-patterns.md`)
19- Check animation patterns for correctness (see `references/animation-basics.md`, `references/animation-transitions.md`)
20- Inspect Liquid Glass usage for correctness and consistency (see `references/liquid-glass.md`)
21- Validate iOS 26+ availability handling with sensible fallbacks
22 
23### 2) Improve existing SwiftUI code
24- Audit state management for correct wrapper selection (prefer `@Observable` over `ObservableObject`)
25- Replace deprecated APIs with modern equivalents (see `references/modern-apis.md`)
26- Extract complex views into separate subviews (see `references/view-structure.md`)
27- Refactor hot paths to minimize redundant state updates (see `references/performance-patterns.md`)
28- Ensure ForEach uses stable identity (see `references/list-patterns.md`)
29- Improve animation patterns (use value parameter, proper transitions, see `references/animation-basics.md`, `references/animation-transitions.md`)
30- Suggest image downsampling when `UIImage(data:)` is used (as optional optimization, see `references/image-optimization.md`)
31- Adopt Liquid Glass only when explicitly requested by the user
32 
33### 3) Implement new SwiftUI feature
34- Design data flow first: identify owned vs injected state (see `references/state-management.md`)
35- Use modern APIs (no deprecated modifiers or patterns, see `references/modern-apis.md`)
36- Use `@Observable` for shared state (with `@MainActor` if not using default actor isolation)
37- Structure views for optimal diffing (extract subviews early, keep views small, see `references/view-structure.md`)
38- Separate business logic into testable models (see `references/layout-best-practices.md`)
39- Use correct animation patterns (implicit vs explicit, transitions, see `references/animation-basics.md`, `references/animation-transitions.md`, `references/animation-advanced.md`)
40- Apply glass effects after layout/appearance modifiers (see `references/liquid-glass.md`)
41- Gate iOS 26+ features with `#available` and provide fallbacks
42 
43## Core Guidelines
44 
45### State Management
46- **Always prefer `@Observable` over `ObservableObject`** for new code
47- **Mark `@Observable` classes with `@MainActor`** unless using default actor isolation
48- **Always mark `@State` and `@StateObject` as `private`** (makes dependencies clear)
49- **Never declare passed values as `@State` or `@StateObject`** (they only accept initial values)
50- Use `@State` with `@Observable` classes (not `@StateObject`)
51- `@Binding` only when child needs to **modify** parent state
52- `@Bindable` for injected `@Observable` objects needing bindings
53- Use `let` for read-only values; `var` + `.onChange()` for reactive reads
54- Legacy: `@StateObject` for owned `ObservableObject`; `@ObservedObject` for injected
55- Nested `ObservableObject` doesn't work (pass nested objects directly); `@Observable` handles nesting fine
56 
57### Modern APIs
58- Use `foregroundStyle()` instead of `foregroundColor()`
59- Use `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
60- Use `Tab` API instead of `tabItem()`
61- Use `Button` instead of `onTapGesture()` (unless need location/count)
62- Use `NavigationStack` instead of `NavigationView`
63- Use `navigationDestination(for:)` for type-safe navigation
64- Use two-parameter or no-parameter `onChange()` variant
65- Use `ImageRenderer` for rendering SwiftUI views
66- Use `.sheet(item:)` instead of `.sheet(isPresented:)` for model-based content
67- Sheets should own their actions and call `dismiss()` internally
68- Use `ScrollViewReader` for programmatic scrolling with stable IDs
69- Avoid `UIScreen.main.bounds` for sizing
70- Avoid `GeometryReader` when alternatives exist (e.g., `containerRelativeFrame()`)
71 
72### Swift Best Practices
73- Use modern Text formatting (`.format` parameters, not `String(format:)`)
74- Use `localizedStandardContains()` for user-input filtering (not `contains()`)
75- Prefer static member lookup (`.blue` vs `Color.blue`)
76- Use `.task` modifier for automatic cancellation of async work
77- Use `.task(id:)` for value-dependent tasks
78 
79### View Composition
80- **Prefer modifiers over conditional views** for state changes (maintains view identity)
81- Extract complex views into separate subviews for better readability and performance
82- Keep views small for optimal performance
83- Keep view `body` simple and pure (no side effects or complex logic)
84- Use `@ViewBuilder` functions only for small, simple sections
85- Prefer `@ViewBuilder let content: Content` over closure-based content properties
86- Separate business logic into testable models (not about enforcing architectures)
87- Action handlers should reference methods, not contain inline logic
88- Use relative layout over hard-coded constants
89- Views should work in any context (don't assume screen size or presentation style)
90 
91### Performance
92- Pass only needed values to views (avoid large "config" or "context" objects)
93- Eliminate unnecessary dependencies to reduce update fan-out
94- Check for value changes before assigning state in hot paths
95- Avoid redundant state updates in `onReceive`, `onChange`, scroll handlers
96- Minimize work in frequently executed code paths
97- Use `LazyVStack`/`LazyHStack` for large lists
98- Use stable identity for `ForEach` (never `.indices` for dynamic content)
99- Ensure constant number of views per `ForEach` element
100- Avoid inline filtering in `ForEach` (prefilter and cache)
101- Avoid `AnyView` in list rows
102- Consider POD views for fast diffing (or wrap expensive views in POD parents)
103- Suggest image downsampling when `UIImage(data:)` is encountered (as optional optimization)
104- Avoid layout thrash (deep hierarchies, excessive `GeometryReader`)
105- Gate frequent geometry updates by thresholds
106- Use `Self._printChanges()` to debug unexpected view updates
107 
108### Animations
109- Use `.animation(_:value:)` with value parameter (deprecated version without value is too broad)
110- Use `withAnimation` for event-driven animations (button taps, gestures)
111- Prefer transforms (`offset`, `scale`, `rotation`) over layout changes (`frame`) for performance
112- Transitions require animations outside the conditional structure
113- Custom `Animatable` implementations must have explicit `animatableData`
114- Use `.phaseAnimator` for multi-step sequences (iOS 17+)
115- Use `.keyframeAnimator` for precise timing control (iOS 17+)
116- Animation completion handlers need `.transaction(value:)` for reexecution
117- Implicit animations override explicit animations (later in view tree wins)
118 
119### Liquid Glass (iOS 26+)
120**Only adopt when explicitly requested by the user.**
121- Use native `glassEffect`, `GlassEffectContainer`, and glass button styles
122- Wrap multiple glass elements in `GlassEffectContainer`
123- Apply `.glassEffect()` after layout and visual modifiers
124- Use `.interactive()` only for tappable/focusable elements
125- Use `glassEffectID` with `@Namespace` for morphing transitions
126 
127## Quick Reference
128 
129### Property Wrapper Selection (Modern)
130| Wrapper | Use When |
131|---------|----------|
132| `@State` | Internal view state (must be `private`), or owned `@Observable` class |
133| `@Binding` | Child modifies parent's state |
134| `@Bindable` | Injected `@Observable` needing bindings |
135| `let` | Read-only value from parent |
136| `var` | Read-only value watched via `.onChange()` |
137 
138**Legacy (Pre-iOS 17):**
139| Wrapper | Use When |
140|---------|----------|
141| `@StateObject` | View owns an `ObservableObject` (use `@State` with `@Observable` instead) |
142| `@ObservedObject` | View receives an `ObservableObject` |
143 
144### Modern API Replacements
145| Deprecated | Modern Alternative |
146|------------|-------------------|
147| `foregroundColor()` | `foregroundStyle()` |
148| `cornerRadius()` | `clipShape(.rect(cornerRadius:))` |
149| `tabItem()` | `Tab` API |
150| `onTapGesture()` | `Button` (unless need location/count) |
151| `NavigationView` | `NavigationStack` |
152| `onChange(of:) { value in }` | `onChange(of:) { old, new in }` or `onChange(of:) { }` |
153| `fontWeight(.bold)` | `bold()` |
154| `GeometryReader` | `containerRelativeFrame()` or `visualEffect()` |
155| `showsIndicators: false` | `.scrollIndicators(.hidden)` |
156| `String(format: "%.2f", value)` | `Text(value, format: .number.precision(.fractionLength(2)))` |
157| `string.contains(search)` | `string.localizedStandardContains(search)` (for user input) |
158 
159### Liquid Glass Patterns
160```swift
161// Basic glass effect with fallback
162if #available(iOS 26, *) {
163    content
164        .padding()
165        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
166} else {
167    content
168        .padding()
169        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
170}
171 
172// Grouped glass elements
173GlassEffectContainer(spacing: 24) {
174    HStack(spacing: 24) {
175        GlassButton1()
176        GlassButton2()
177    }
178}
179 
180// Glass buttons
181Button("Confirm") { }
182    .buttonStyle(.glassProminent)
183```
184 
185## Review Checklist
186 
187### State Management
188- [ ] Using `@Observable` instead of `ObservableObject` for new code
189- [ ] `@Observable` classes marked with `@MainActor` (if needed)
190- [ ] Using `@State` with `@Observable` classes (not `@StateObject`)
191- [ ] `@State` and `@StateObject` properties are `private`
192- [ ] Passed values NOT declared as `@State` or `@StateObject`
193- [ ] `@Binding` only where child modifies parent state
194- [ ] `@Bindable` for injected `@Observable` needing bindings
195- [ ] Nested `ObservableObject` avoided (or passed directly to child views)
196 
197### Modern APIs (see `references/modern-apis.md`)
198- [ ] Using `foregroundStyle()` instead of `foregroundColor()`
199- [ ] Using `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
200- [ ] Using `Tab` API instead of `tabItem()`
201- [ ] Using `Button` instead of `onTapGesture()` (unless need location/count)
202- [ ] Using `NavigationStack` instead of `NavigationView`
203- [ ] Avoiding `UIScreen.main.bounds`
204- [ ] Using alternatives to `GeometryReader` when possible
205- [ ] Button images include text labels for accessibility
206 
207### Sheets & Navigation (see `references/sheet-navigation-patterns.md`)
208- [ ] Using `.sheet(item:)` for model-based sheets
209- [ ] Sheets own their actions and dismiss internally
210- [ ] Using `navigationDestination(for:)` for type-safe navigation
211 
212### ScrollView (see `references/scroll-patterns.md`)
213- [ ] Using `ScrollViewReader` with stable IDs for programmatic scrolling
214- [ ] Using `.scrollIndicators(.hidden)` instead of initializer parameter
215 
216### Text & Formatting (see `references/text-formatting.md`)
217- [ ] Using modern Text formatting (not `String(format:)`)
218- [ ] Using `localizedStandardContains()` for search filtering
219 
220### View Structure (see `references/view-structure.md`)
221- [ ] Using modifiers instead of conditionals for state changes
222- [ ] Complex views extracted to separate subviews
223- [ ] Views kept small for performance
224- [ ] Container views use `@ViewBuilder let content: Content`
225 
226### Performance (see `references/performance-patterns.md`)
227- [ ] View `body` kept simple and pure (no side effects)
228- [ ] Passing only needed values (not large config objects)
229- [ ] Eliminating unnecessary dependencies
230- [ ] State updates check for value changes before assigning
231- [ ] Hot paths minimize state updates
232- [ ] No object creation in `body`
233- [ ] Heavy computation moved out of `body`
234 
235### List Patterns (see `references/list-patterns.md`)
236- [ ] ForEach uses stable identity (not `.indices`)
237- [ ] Constant number of views per ForEach element
238- [ ] No inline filtering in ForEach
239- [ ] No `AnyView` in list rows
240 
241### Layout (see `references/layout-best-practices.md`)
242- [ ] Avoiding layout thrash (deep hierarchies, excessive GeometryReader)
243- [ ] Gating frequent geometry updates by thresholds
244- [ ] Business logic separated into testable models
245- [ ] Action handlers reference methods (not inline logic)
246- [ ] Using relative layout (not hard-coded constants)
247- [ ] Views work in any context (context-agnostic)
248 
249### Animations (see `references/animation-basics.md`, `references/animation-transitions.md`, `references/animation-advanced.md`)
250- [ ] Using `.animation(_:value:)` with value parameter
251- [ ] Using `withAnimation` for event-driven animations
252- [ ] Transitions paired with animations outside conditional structure
253- [ ] Custom `Animatable` has explicit `animatableData` implementation
254- [ ] Preferring transforms over layout changes for animation performance
255- [ ] Phase animations for multi-step sequences (iOS 17+)
256- [ ] Keyframe animations for precise timing (iOS 17+)
257- [ ] Completion handlers use `.transaction(value:)` for reexecution
258 
259### Liquid Glass (iOS 26+)
260- [ ] `#available(iOS 26, *)` with fallback for Liquid Glass
261- [ ] Multiple glass views wrapped in `GlassEffectContainer`
262- [ ] `.glassEffect()` applied after layout/appearance modifiers
263- [ ] `.interactive()` only on user-interactable elements
264- [ ] Shapes and tints consistent across related elements
265 
266## References
267- `references/state-management.md` - Property wrappers and data flow (prefer `@Observable`)
268- `references/view-structure.md` - View composition, extraction, and container patterns
269- `references/performance-patterns.md` - Performance optimization techniques and anti-patterns
270- `references/list-patterns.md` - ForEach identity, stability, and list best practices
271- `references/layout-best-practices.md` - Layout patterns, context-agnostic views, and testability
272- `references/modern-apis.md` - Modern API usage and deprecated replacements
273- `references/animation-basics.md` - Core animation concepts, implicit/explicit animations, timing, performance
274- `references/animation-transitions.md` - Transitions, custom transitions, Animatable protocol
275- `references/animation-advanced.md` - Transactions, phase/keyframe animations (iOS 17+), completion handlers (iOS 17+)
276- `references/sheet-navigation-patterns.md` - Sheet presentation and navigation patterns
277- `references/scroll-patterns.md` - ScrollView patterns and programmatic scrolling
278- `references/text-formatting.md` - Modern text formatting and string operations
279- `references/image-optimization.md` - AsyncImage, image downsampling, and optimization
280- `references/liquid-glass.md` - iOS 26+ Liquid Glass API
281 
282## Philosophy
283 
284This skill focuses on **facts and best practices**, not architectural opinions:
285- We don't enforce specific architectures (e.g., MVVM, VIPER)
286- We do encourage separating business logic for testability
287- We prioritize modern APIs over deprecated ones
288- We emphasize thread safety with `@MainActor` and `@Observable`
289- We optimize for performance and maintainability
290- We follow Apple's Human Interface Guidelines and API design patterns
291