swiftui-expert-skill

Type	Skill
Plugin	awl-ios · v0.0.6
Invoke	/awl-ios:swiftui-expert-skill
Source	plugins/awl-ios/skills/swiftui-expert-skill/SKILL.md

When Claude uses it

Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift 6 concurrency with main-actor default isolation, and iOS 26+ Liquid Glass adoption. Use when the user says “build a SwiftUI view”, “create a screen”, “add a view model”, “review this SwiftUI code”, “refactor this view”, “why does this view re-render”, or asks about @Observable, @State, navigation, sheets, lists, or Liquid Glass. NOT for writing tests (use awl-testing testing-swift), not for build, simulator, or fastlane commands (use awl-ios-ref), not for KMP shared Kotlin code (use awl-android kotlin-expert).

Trigger phrases: build a SwiftUI view · create a screen · add a view model · review this SwiftUI code · refactor this view · why does this view re-render

Definition

Overview

Use 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.

Project baseline (AWL template)

The AWL iOS template sets these in Project.swift, so every app and feature target compiles under them:

Setting	Value	Consequence for SwiftUI code
SWIFT_VERSION	6.0	Strict concurrency is on; data races are compile errors, not warnings
SWIFT_DEFAULT_ACTOR_ISOLATION	MainActor	Every type and function is main-actor isolated unless marked nonisolated, so @MainActor on views and @Observable classes is redundant
SWIFT_APPROACHABLE_CONCURRENCY	YES	nonisolated async functions run on the caller’s actor; use @concurrent to move work off the main actor
minIosVersion	26.4 (template), 18.0 (KMP iOS shell)	No #available gates for iOS 17 or 18 APIs; Liquid Glass fallbacks only in the KMP shell

Write @MainActor explicitly only in Swift packages or targets that do not carry these settings, because there the compiler infers nonisolated. Verify with grep SWIFT_DEFAULT_ACTOR_ISOLATION Project.swift when a project is not built from the template.

Workflow Decision Tree

1) Review existing SwiftUI code

• Check property wrapper usage against the selection guide (see references/state-management.md)
• Verify modern API usage (see references/modern-apis.md)
• Verify view composition follows extraction rules (see references/view-structure.md)
• Check performance patterns are applied (see references/performance-patterns.md)
• Verify list patterns use stable identity (see references/list-patterns.md)
• Inspect Liquid Glass usage for correctness and consistency (see references/liquid-glass.md)
• Validate iOS 26+ availability handling with sensible fallbacks

2) Improve existing SwiftUI code

• Audit state management for correct wrapper selection (prefer @Observable over ObservableObject)
• Replace deprecated APIs with modern equivalents (see references/modern-apis.md)
• Extract complex views into separate subviews (see references/view-structure.md)
• Refactor hot paths to minimize redundant state updates (see references/performance-patterns.md)
• Ensure ForEach uses stable identity (see references/list-patterns.md)
• Suggest image downsampling when UIImage(data:) is used (as optional optimization, see references/image-optimization.md)
• Adopt Liquid Glass only when explicitly requested by the user

3) Implement new SwiftUI feature

• Design data flow first: identify owned vs injected state (see references/state-management.md)
• Use modern APIs (no deprecated modifiers or patterns, see references/modern-apis.md)
• Use @Observable for shared state; skip @MainActor in template targets because default actor isolation is MainActor
• Put CPU-heavy work (image decoding, parsing, sorting large arrays) in a @concurrent function so the main actor stays free
• Structure views for optimal diffing (extract subviews early, keep views small, see references/view-structure.md)
• Separate business logic into testable models (see references/layout-best-practices.md)
• Apply glass effects after layout/appearance modifiers (see references/liquid-glass.md)
• Gate iOS 26+ features with #available and provide fallbacks

Core Guidelines

State Management

• Always prefer @Observable over ObservableObject for new code
• Leave @MainActor off @Observable classes in template targets because SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor already isolates them; add it only in packages without that setting
• Always mark @State and @StateObject as private (makes dependencies clear)
• Never declare passed values as @State or @StateObject (they only accept initial values)
• Use @State with @Observable classes (not @StateObject)
• @Binding only when child needs to modify parent state
• @Bindable for injected @Observable objects needing bindings
• Use let for read-only values; var + .onChange() for reactive reads
• Legacy: @StateObject for owned ObservableObject; @ObservedObject for injected
• Nested ObservableObject doesn’t work (pass nested objects directly); @Observable handles nesting fine

Modern APIs

• Use foregroundStyle() instead of foregroundColor()
• Use clipShape(.rect(cornerRadius:)) instead of cornerRadius()
• Use Tab API instead of tabItem()
• Use Button instead of onTapGesture() (unless need location/count)
• Use NavigationStack instead of NavigationView
• Use navigationDestination(for:) for type-safe navigation
• Use two-parameter or no-parameter onChange() variant
• Use ImageRenderer for rendering SwiftUI views
• Use .sheet(item:) instead of .sheet(isPresented:) for model-based content
• Sheets should own their actions and call dismiss() internally
• Use ScrollViewReader for programmatic scrolling with stable IDs
• Avoid UIScreen.main.bounds for sizing
• Avoid GeometryReader when alternatives exist (e.g., containerRelativeFrame())

Swift Best Practices

• Use modern Text formatting (.format parameters, not String(format:))
• Use localizedStandardContains() for user-input filtering (not contains())
• Prefer static member lookup (.blue vs Color.blue)
• Use .task modifier for automatic cancellation of async work
• Use .task(id:) for value-dependent tasks
• Under approachable concurrency a nonisolated async function stays on the caller’s actor, so mark heavy work @concurrent instead of reaching for Task.detached or DispatchQueue
• Values that cross into a @concurrent function or out of it must be Sendable; prefer structs and let over classes for such data

View Composition

• Prefer modifiers over conditional views for state changes (maintains view identity)
• Extract complex views into separate subviews for better readability and performance
• Keep views small for optimal performance
• Keep view body simple and pure (no side effects or complex logic)
• Use @ViewBuilder functions only for small, simple sections
• Prefer @ViewBuilder let content: Content over closure-based content properties
• Separate business logic into testable models (not about enforcing architectures)
• Action handlers should reference methods, not contain inline logic
• Use relative layout over hard-coded constants
• Views should work in any context (don’t assume screen size or presentation style)

Performance

• Pass only needed values to views (avoid large “config” or “context” objects)
• Eliminate unnecessary dependencies to reduce update fan-out
• Check for value changes before assigning state in hot paths
• Avoid redundant state updates in onReceive, onChange, scroll handlers
• Minimize work in frequently executed code paths
• Use LazyVStack/LazyHStack for large lists
• Use stable identity for ForEach (never .indices for dynamic content)
• Ensure constant number of views per ForEach element
• Avoid inline filtering in ForEach (prefilter and cache)
• Avoid AnyView in list rows
• Consider POD views for fast diffing (or wrap expensive views in POD parents)
• Suggest image downsampling when UIImage(data:) is encountered (as optional optimization)
• Avoid layout thrash (deep hierarchies, excessive GeometryReader)
• Gate frequent geometry updates by thresholds
• Use Self._printChanges() to debug unexpected view updates

Liquid Glass (iOS 26+)

Only adopt when explicitly requested by the user.

• Use native glassEffect, GlassEffectContainer, and glass button styles
• Wrap multiple glass elements in GlassEffectContainer
• Apply .glassEffect() after layout and visual modifiers
• Use .interactive() only for tappable/focusable elements
• Use glassEffectID with @Namespace for morphing transitions

Quick Reference

Property Wrapper Selection (Modern)

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()

Legacy (Pre-iOS 17, below every AWL template deployment target):

Wrapper	Use When
@StateObject	View owns an ObservableObject (use @State with @Observable instead)
@ObservedObject	View receives an ObservableObject

Modern API Replacements

Deprecated	Modern Alternative
foregroundColor()	foregroundStyle()
cornerRadius()	clipShape(.rect(cornerRadius:))
tabItem()	Tab API
onTapGesture()	Button (unless need location/count)
NavigationView	NavigationStack
onChange(of:) { value in }	onChange(of:) { old, new in } or onChange(of:) { }
fontWeight(.bold)	bold()
GeometryReader	containerRelativeFrame() or visualEffect()
showsIndicators: false	.scrollIndicators(.hidden)
String(format: "%.2f", value)	Text(value, format: .number.precision(.fractionLength(2)))
string.contains(search)	string.localizedStandardContains(search) (for user input)

Liquid Glass Patterns

// Basic glass effect with fallback
if #available(iOS 26, *) {
    content
        .padding()
        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
} else {
    content
        .padding()
        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
}

// Grouped glass elements
GlassEffectContainer(spacing: 24) {
    HStack(spacing: 24) {
        GlassButton1()
        GlassButton2()
    }
}

// Glass buttons
Button("Confirm") { }
    .buttonStyle(.glassProminent)

Review Checklist

State Management

• Using @Observable instead of ObservableObject for new code
• No redundant @MainActor on @Observable classes in targets with SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor
• Heavy work runs in a @concurrent function, not in Task.detached or DispatchQueue
• Using @State with @Observable classes (not @StateObject)
• @State and @StateObject properties are private
• Passed values NOT declared as @State or @StateObject
• @Binding only where child modifies parent state
• @Bindable for injected @Observable needing bindings
• Nested ObservableObject avoided (or passed directly to child views)

Modern APIs (see references/modern-apis.md)

• Using foregroundStyle() instead of foregroundColor()
• Using clipShape(.rect(cornerRadius:)) instead of cornerRadius()
• Using Tab API instead of tabItem()
• Using Button instead of onTapGesture() (unless need location/count)
• Using NavigationStack instead of NavigationView
• Avoiding UIScreen.main.bounds
• Using alternatives to GeometryReader when possible
• Button images include text labels for accessibility

Sheets & Navigation (see references/sheet-navigation-patterns.md)

• Using .sheet(item:) for model-based sheets
• Sheets own their actions and dismiss internally
• Using navigationDestination(for:) for type-safe navigation

ScrollView (see references/scroll-patterns.md)

• Using ScrollViewReader with stable IDs for programmatic scrolling
• Using .scrollIndicators(.hidden) instead of initializer parameter

Text & Formatting (see references/text-formatting.md)

• Using modern Text formatting (not String(format:))
• Using localizedStandardContains() for search filtering

View Structure (see references/view-structure.md)

• Using modifiers instead of conditionals for state changes
• Complex views extracted to separate subviews
• Views kept small for performance
• Container views use @ViewBuilder let content: Content

Performance (see references/performance-patterns.md)

• View body kept simple and pure (no side effects)
• Passing only needed values (not large config objects)
• Eliminating unnecessary dependencies
• State updates check for value changes before assigning
• Hot paths minimize state updates
• No object creation in body
• Heavy computation moved out of body

List Patterns (see references/list-patterns.md)

• ForEach uses stable identity (not .indices)
• Constant number of views per ForEach element
• No inline filtering in ForEach
• No AnyView in list rows

Layout (see references/layout-best-practices.md)

• Avoiding layout thrash (deep hierarchies, excessive GeometryReader)
• Gating frequent geometry updates by thresholds
• Business logic separated into testable models
• Action handlers reference methods (not inline logic)
• Using relative layout (not hard-coded constants)
• Views work in any context (context-agnostic)

Liquid Glass (iOS 26+)

• #available(iOS 26, *) with fallback for Liquid Glass
• Multiple glass views wrapped in GlassEffectContainer
• .glassEffect() applied after layout/appearance modifiers
• .interactive() only on user-interactable elements
• Shapes and tints consistent across related elements

References

• references/state-management.md - Property wrappers and data flow (prefer @Observable)
• references/view-structure.md - View composition, extraction, and container patterns
• references/performance-patterns.md - Performance optimization techniques and anti-patterns
• references/list-patterns.md - ForEach identity, stability, and list best practices
• references/layout-best-practices.md - Layout patterns, context-agnostic views, and testability
• references/modern-apis.md - Modern API usage and deprecated replacements
• references/sheet-navigation-patterns.md - Sheet presentation and navigation patterns
• references/scroll-patterns.md - ScrollView patterns and programmatic scrolling
• references/text-formatting.md - Modern text formatting and string operations
• references/image-optimization.md - AsyncImage, image downsampling, and optimization
• references/liquid-glass.md - iOS 26+ Liquid Glass API

Philosophy

This skill focuses on facts and best practices, not architectural opinions:

• We don’t enforce specific architectures (e.g., MVVM, VIPER)
• We do encourage separating business logic for testability
• We prioritize modern APIs over deprecated ones
• We rely on Swift 6 strict concurrency with main-actor default isolation for thread safety, and move heavy work off the main actor with @concurrent
• We optimize for performance and maintainability
• We follow Apple’s Human Interface Guidelines and API design patterns