Swiftui Expert

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SwiftyJourney
• Source: SwiftyJourney/swiftui-expert-skill
• License: MIT

Install and usage instructions live in the source repository linked above.