SwiftUI Mastery
Use when building, reviewing, debugging, or refactoring SwiftUI on Apple platforms, especially for state management, layout, navigation, component patterns, animation, accessibility, or performance. A
SKILL.mdskills/apple/swiftui-mastery_KM/SKILL.md
GitHub<!-- Merged from: apple-swiftui-mastery, swiftui-expert-skill, swiftui-ui-patterns (2026-03-30) -->
<!-- Merged from: swiftui-performance-audit (2026-03-31) -->
SwiftUI Mastery
Expert guidance for building, reviewing, and architecting SwiftUI UIs on all Apple platforms. Covers state management, layout, navigation, animations, accessibility, performance, and component patterns.
Operating Rules
- Consult
references/latest-apis.mdat the start of every task to check for deprecated APIs - Prefer native SwiftUI APIs over UIKit/AppKit bridging unless bridging is explicitly needed
- Use
#availablegating with sensible fallbacks for version-specific APIs (iOS 16+, iOS 17+, iOS 26+) - Separate business logic from views for testability — without mandating a specific architecture
- Follow Apple's Human Interface Guidelines
- Only adopt Liquid Glass when explicitly requested (see the
liquid-glassskill) @Stateproperties should always beprivate
Task Workflow
Review existing SwiftUI code
- Identify which topics apply (state management, layout, navigation, performance, accessibility)
- Flag deprecated APIs using
references/latest-apis.md - Check
#availablegating and fallback paths for iOS 26+ features - Validate the Correctness Checklist below
Improve existing SwiftUI code
- Audit against the Topic Router
- 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 (seereferences/image-optimization.md)
Implement a 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
Buttonfor all tappable elements; add accessibility grouping and labels - Gate version-specific APIs with
#availableand provide fallbacks
Scaffold a new project or screen
- Start with
references/app-wiring.mdto wire TabView + NavigationStack + sheets - Add a minimal
AppTabenum and per-tab router - Choose component references from
references/components-index.mdbased on UI needs - Expand route and sheet enums as new screens are added
Topic Router
Consult the reference file for each topic relevant to the current task:
| Topic | Reference |
|---|---|
| Deprecated → modern API lookup | references/latest-apis.md — Read first every task |
| State management & @Observable | references/state-management.md |
| View composition & extraction | references/view-structure.md |
| Performance & update control | references/performance-patterns.md |
| Performance audit (Instruments guide) | references/optimizing-swiftui-performance-instruments.md |
| Performance audit (understanding & improving) | references/understanding-improving-swiftui-performance.md |
| Performance audit (hangs) | references/understanding-hangs-in-your-app.md |
| Performance audit (WWDC23 deep dive) | references/demystify-swiftui-performance-wwdc23.md |
| Lists, ForEach & Table | references/list-patterns.md |
| Layout & GeometryReader alternatives | references/layout-best-practices.md |
| Sheets & navigation | references/sheet-navigation-patterns.md |
| ScrollView patterns | references/scroll-patterns.md |
| Animations (basics) | references/animation-basics.md |
| Animations (transitions) | references/animation-transitions.md |
| Animations (advanced / iOS 17+) | references/animation-advanced.md |
| Accessibility & Dynamic Type | references/accessibility-patterns.md |
| Swift Charts | references/charts.md |
| Charts accessibility | references/charts-accessibility.md |
| Image optimization | references/image-optimization.md |
| macOS scenes & windows | references/macos-scenes.md |
| macOS window styling | references/macos-window-styling.md |
| macOS-specific views | references/macos-views.md |
| App shell / tab + nav wiring | references/app-wiring.md |
| Component patterns index | references/components-index.md |
| Component: TabView | references/tabview.md |
| Component: NavigationStack | references/navigationstack.md |
| Component: Sheets | references/sheets.md |
| Component: List | references/list.md |
| Component: ScrollView | references/scrollview.md |
| Component: Grids | references/grids.md |
| Component: Forms | references/form.md |
| Component: Controls | references/controls.md |
| Component: Overlays | references/overlay.md |
| Component: Split views | references/split-views.md |
| Component: Searchable | references/searchable.md |
| Component: Focus | references/focus.md |
| Component: Haptics | references/haptics.md |
| Component: Media | references/media.md |
| Component: Loading/Placeholders | references/loading-placeholders.md |
| Component: Input toolbar | references/input-toolbar.md |
| Component: Matched transitions | references/matched-transitions.md |
| Component: Theming | references/theming.md |
| Component: Top bar | references/top-bar.md |
| Component: Title menus | references/title-menus.md |
| Component: Menu bar (macOS) | references/menu-bar.md |
| Component: macOS Settings | references/macos-settings.md |
| Component: Deep links | references/deeplinks.md |
| Component: Lightweight clients | references/lightweight-clients.md |
Correctness Checklist
Violations are always bugs — check these on every review:
-
@Stateproperties areprivate -
@Bindingonly where a child modifies parent state - Values passed in from parent are never declared as
@Stateor@StateObject(they ignore updates) -
@StateObjectfor view-owned objects;@ObservedObjectfor injected objects - iOS 17+: use
@Statewith@Observable; use@Bindablefor injected observables needing bindings -
ForEachuses stable identity — never.indicesfor dynamic content - Constant number of views per
ForEachelement -
.animation(_:value:)always includes thevalueparameter - iOS 26+ APIs gated with
#available(iOS 26, *)and a fallback provided -
import Chartspresent in files using chart types
State Management Summary
SwiftUI provides several property wrappers — choose based on who owns the state:
@State— simple value types owned by a single view; expose to children as@Binding@Binding— two-way reference into parent state; use$prefix to derive from@State@StateObject— creates and owns anObservableObject; persists across view re-creations@ObservedObject— subscribes to anObservableObjectinjected from a parent; does NOT persist@EnvironmentObject— shared model injected into the hierarchy; use for global app state@Environment— read system values (colorScheme, dynamicTypeSize) or customEnvironmentKeys@Observable(iOS 17+) — marks a class for automatic observation; combine with@Stateor@Environment; no need for@Published
For edge cases including computed bindings, combining wrappers, and avoiding value type mutation pitfalls: see references/state-management.md.
Layout Key Points
- Use
HStack,VStack,ZStackfor standard composition;LazyVGrid/LazyHGrid/Gridfor collections Layoutprotocol (iOS 16+): implementsizeThatFitsandplaceSubviewsfor fully custom layoutsGeometryReader: takes all available space unless constrained — wrap in aframeor use as overlay/background; preferLayoutprotocol orViewThatFitsoverGeometryReaderwhere possiblePreferenceKey: lets child views send information up the hierarchy — essential for measuring sizes or aligning siblings- For complex layout patterns (flow, tag cloud, flexible grid): see
references/layout-best-practices.md
Navigation Patterns
- Use
NavigationStack(iOS 16+) withNavigationPathfor programmatic navigation; conform data toHashableand use.navigationDestination(for:) - Use
NavigationSplitViewfor two- or three-column layouts on iPad and macOS - Present secondary content with
.sheetor.fullScreenCover; use.presentationDetents(iOS 16+) for medium/large/custom heights - For deep linking: decode URLs into path elements; see
references/sheet-navigation-patterns.md
Sheet Patterns
Item-driven sheet (preferred over isPresented)
@State private var selectedItem: Item?
.sheet(item: $selectedItem) { item in
EditItemSheet(item: item)
}
Sheet owns its actions
struct EditItemSheet: View {
@Environment(\.dismiss) private var dismiss
@Environment(Store.self) private var store
let item: Item
@State private var isSaving = false
var body: some View {
Button(isSaving ? "Saving…" : "Save") {
Task { await save() }
}
}
private func save() async {
isSaving = true
await store.save(item)
dismiss()
}
}
Prefer .sheet(item:) when state represents a selected model. Sheets should call dismiss() internally — avoid forwarding onCancel/onConfirm closures to the parent.
Animations Summary
- Wrap state mutations in
withAnimation { }for automatic animation; use.animation(_:value:)on individual views for targeted control - Use
.transition()for appear/disappear effects:.opacity,.slide,.scale,.move matchedGeometryEffect(id:in:isSource:)synchronises geometry across views for hero transitions- iOS 17+: phase animators and keyframe animations for complex sequenced motion
- iOS 26+:
@Animatablemacro for custom animatable properties - For advanced spring curves, keyframe examples: see
references/animation-advanced.md
Performance Anti-Patterns
Avoid these — each is a class of bug or performance issue:
- Performing network requests or heavy work inside
body— use.taskor separate model layers - Overusing
GeometryReader— preferLayoutprotocol orLayoutPriority - Creating new objects or closures every
bodyevaluation (memory churn) — use@StateObjector constants - Using
.onAppearfor repeating timers — useTimelineViewfor scheduled updates - Modifying state inside a view's
init()— causes unpredictable behavior - Excessive global state through
@EnvironmentObject— obscures data flow
Performance Audit Workflow
Use this structured workflow when diagnosing slow rendering, janky scrolling, high CPU/memory, excessive view updates, or layout thrash.
Decision tree:
- If the user provides code → start with Code-First Review
- If the user only describes symptoms → ask for minimal code/context, then do Code-First Review
- If code review is inconclusive → Guide Profiling with Instruments
1. Code-First Review
Collect: target view/feature code, data flow (state, environment, observable models), symptoms and reproduction steps.
Focus on:
- View invalidation storms from broad state changes
- Unstable identity in lists (
idchurn,UUID()per render) - Top-level conditional view swapping (
if/elsereturning different root branches) - Heavy work in
body(formatting, sorting, image decoding) - Layout thrash (deep stacks,
GeometryReader, preference chains) - Large images without downsampling or resizing
- Over-animated hierarchies (implicit animations on large trees)
2. Guide Profiling with Instruments
When code review is inconclusive, ask the user to:
- Open Instruments → SwiftUI template (use a Release build)
- Reproduce the exact interaction (scroll, navigation, animation)
- Capture the SwiftUI timeline and Time Profiler call tree
- Export or screenshot the relevant lanes
Ask for: trace export or screenshots of SwiftUI lanes + Time Profiler, device/OS/build configuration.
See references/optimizing-swiftui-performance-instruments.md and references/demystify-swiftui-performance-wwdc23.md for guidance on reading traces.
3. Diagnose
Prioritize the culprits listed in step 1. Summarize findings with evidence from traces/logs.
4. Remediate
Apply targeted fixes:
- Narrow state scope (
@State/@Observablecloser to leaf views) - Stabilize identities for
ForEachand lists - Move heavy work out of
body(precompute, cache,@State) - Use
equatable()or value wrappers for expensive subtrees - Downsample images before rendering
- Reduce layout complexity or use fixed sizing where possible
5. Verify
Ask the user to re-run the same capture and compare with baseline. Summarize the delta (CPU, frame drops, memory peak) if provided. Provide: short metrics table (before/after), top issues ordered by impact, proposed fixes with estimated effort.
Common Code Smells
Expensive formatters in body — allocating NumberFormatter/MeasurementFormatter each evaluation. Fix: cache in a shared helper or model.
Computed properties doing heavy work — var filtered: [Item] { items.filter { ... } } runs on every body eval. Fix: precompute and cache using @State updated on change.
Sorting/filtering inside ForEach — ForEach(items.sorted(by:)) re-sorts every render. Fix: sort once before view updates.
Unstable identity — ForEach(items, id: \.self) on non-stable values. Fix: use a stable ID (e.g., a persistent UUID stored on the model).
Top-level conditional view swapping — if isEditing { editingView } else { readOnlyView } causes root identity churn. Fix: one stable base view; localize conditions to toolbar, overlays, or modifiers.
Image decoding on the main thread — UIImage(data: data). Fix: decode/downsample off the main thread and store the result (see references/image-optimization.md).
Broad dependencies in observable models — a view reading model.items.contains(item) re-renders on any items change. Fix: granular view models or per-item state to reduce update fan-out.
Workflow for a New View
- Define the view's state and where it lives (local, parent-owned, environment)
- Identify dependencies to inject via
@Environment - Sketch the view hierarchy; extract repeated parts into subviews
- Implement async loading with
.taskand an explicit loading/error state enum - Add accessibility labels for all interactive elements
- Validate with a build; update callsites as needed
iOS 26+ Notable APIs
Gridfor fully automatic grid layoutsFlowLayoutfor wrapping content- Improved sheet detents and
presentationCompactMode @Animatablemacro for custom animatable propertiesChart3Dfor 3D charting (seereferences/charts.md)- Liquid Glass design language — see the dedicated
liquid-glassskill
Reference Files
All reference files live in references/. Read only the ones relevant to your current task.
Always read first: references/latest-apis.md — deprecated-to-modern API transitions (iOS 15 through iOS 26+)
For component-specific guidance, use references/components-index.md as the entry point — it lists intent, best-fit scenarios, pitfalls, and links for each component.
Performance audit references: references/optimizing-swiftui-performance-instruments.md, references/understanding-improving-swiftui-performance.md, references/understanding-hangs-in-your-app.md, references/demystify-swiftui-performance-wwdc23.md