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

Quick Summary

Quick Reference

Property Wrapper Selection

Full guide including legacy wrappers: state-management.md

Modern API Replacements

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