swiftui-expert-skill

name	swiftui-expert-skill
description	Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, macOS-specific APIs, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns.

SwiftUI Expert Skill

Operating Rules

• Consult references/latest-apis.md at the start of every task to avoid deprecated APIs
• Prefer native SwiftUI APIs over UIKit/AppKit bridging unless bridging is necessary
• Focus on correctness and performance; do not enforce specific architectures (MVVM, VIPER, etc.)
• Encourage separating business logic from views for testability without mandating how
• Follow Apple's Human Interface Guidelines and API design patterns
• Only adopt Liquid Glass when explicitly requested by the user (see references/liquid-glass.md)
• Present performance optimizations as suggestions, not requirements
• Use #available gating with sensible fallbacks for version-specific APIs

Task Workflow

Review existing SwiftUI code

• Read the code under review and identify which topics apply
• Flag deprecated APIs (compare against references/latest-apis.md)
• Run the Topic Router below for each relevant topic
• Validate #available gating and fallback paths for iOS 26+ features

Improve existing SwiftUI code

• Audit current implementation against the Topic Router topics
• Replace deprecated APIs with modern equivalents from references/latest-apis.md
• Refactor hot paths to reduce unnecessary state updates
• Extract complex view bodies into separate subviews
• Suggest image downsampling when UIImage(data:) is encountered (optional optimization, see references/image-optimization.md)

Implement new SwiftUI feature

• Design data flow first: identify owned vs injected state
• Structure views for optimal diffing (extract subviews early)
• Apply correct animation patterns (implicit vs explicit, transitions)
• Use Button for all tappable elements; add accessibility grouping and labels
• Gate version-specific APIs with #available and provide fallbacks

Topic Router

Consult the reference file for each topic relevant to the current task:

Topic	Reference
State management	references/state-management.md
View composition	references/view-structure.md
Performance	references/performance-patterns.md
Lists and ForEach	references/list-patterns.md
Layout	references/layout-best-practices.md
Sheets and navigation	references/sheet-navigation-patterns.md
ScrollView	references/scroll-patterns.md
Focus management	references/focus-patterns.md
Animations (basics)	references/animation-basics.md
Animations (transitions)	references/animation-transitions.md
Animations (advanced)	references/animation-advanced.md
Accessibility	references/accessibility-patterns.md
Swift Charts	references/charts.md
Charts accessibility	references/charts-accessibility.md
Image optimization	references/image-optimization.md
Liquid Glass (iOS 26+)	references/liquid-glass.md
macOS scenes	references/macos-scenes.md
macOS window styling	references/macos-window-styling.md
macOS views	references/macos-views.md
Deprecated API lookup	references/latest-apis.md

Correctness Checklist

These are hard rules -- violations are always bugs:

• @State properties are private
• @Binding only where a child modifies parent state
• Passed values never declared as @State or @StateObject (they ignore updates)
• @StateObject for view-owned objects; @ObservedObject for injected
• iOS 17+: @State with @Observable; @Bindable for injected observables needing bindings
• ForEach uses stable identity (never .indices for dynamic content)
• Constant number of views per ForEach element
• .animation(_:value:) always includes the value parameter
• @FocusState properties are private
• No redundant @FocusState writes inside tap gesture handlers on .focusable() views
• iOS 26+ APIs gated with #available and fallback provided
• import Charts present in files using chart types

References

• references/latest-apis.md -- Read first for every task. Deprecated-to-modern API transitions (iOS 15+ through iOS 26+)
• references/state-management.md -- Property wrappers, data flow, @Observable migration
• references/view-structure.md -- View extraction, container patterns, @ViewBuilder
• references/performance-patterns.md -- Hot-path optimization, update control, _logChanges()
• references/list-patterns.md -- ForEach identity, Table (iOS 16+), inline filtering pitfalls
• references/layout-best-practices.md -- Layout patterns, GeometryReader alternatives
• references/accessibility-patterns.md -- VoiceOver, Dynamic Type, grouping, traits
• references/animation-basics.md -- Implicit/explicit animations, timing, performance
• references/animation-transitions.md -- View transitions, matchedGeometryEffect, Animatable
• references/animation-advanced.md -- Phase/keyframe animations (iOS 17+), @Animatable macro (iOS 26+)
• references/charts.md -- Swift Charts marks, axes, selection, styling, Chart3D (iOS 26+)
• references/charts-accessibility.md -- Charts VoiceOver, Audio Graph, fallback strategies
• references/sheet-navigation-patterns.md -- Sheets, NavigationSplitView, Inspector
• references/scroll-patterns.md -- ScrollViewReader, programmatic scrolling
• references/focus-patterns.md -- Focus state, focusable views, focused values, default focus, common pitfalls
• references/image-optimization.md -- AsyncImage, downsampling, caching
• references/liquid-glass.md -- iOS 26+ Liquid Glass effects and fallback patterns
• references/macos-scenes.md -- Settings, MenuBarExtra, WindowGroup, multi-window
• references/macos-window-styling.md -- Toolbar styles, window sizing, Commands
• references/macos-views.md -- HSplitView, Table, PasteButton, AppKit interop