swiftui-expert-skill

SwiftUI Expert Skill

Operating Rules

Consult references/latest-apis.md at the start of every task to avoid deprecated APIs
Only adopt Liquid Glass when explicitly requested by the user (use the swiftui-liquid-glass skill)
Use #available gating with sensible fallbacks for version-specific APIs

SwiftUI Code 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

Instruments Trace Workflow

Record a new Instruments trace

Trigger when the user asks to “record a trace”, “profile the app”, “capture a session”, etc. Full reference: references/trace-recording.md.

Confirm target — attach to a running app, launch an app, or record all processes? If the user didn’t say, ask. List connected devices when useful:
Terminal window
```
python3 "${SKILL_DIR}/scripts/record_trace.py" --list-devices
```
Pick a template based on target kind — the SwiftUI template populates the SwiftUI lane on any real device: a physical iOS/iPadOS device or the host Mac. The only exception is the iOS Simulator, where the SwiftUI lane comes back empty — switch to --template "Time Profiler" in that case (still gives Time Profiler + Hangs + Animation Hitches). Always check --list-devices: simulators kind → Time Profiler; devices kind (real devices and the host Mac) → default SwiftUI. Full decision table in references/trace-recording.md.
Start the recording. For agent-driven sessions where the user says “I’ll tell you when I’m done”, start in the background and use a stop-file:
Terminal window
```
python3 "${SKILL_DIR}/scripts/record_trace.py" \
    --device "<name|udid>" --attach "<AppName>" \
    --stop-file /tmp/stop-trace --output ~/Desktop/session.trace
```
For interactive sessions, just tell the user to press Ctrl+C when done.
Signal stop — when the user says they’ve finished exercising the app, touch /tmp/stop-trace. The script cleanly SIGINTs xctrace and waits up to 60s for finalisation.
Analyse the resulting trace (flow into the “Trace-driven improvement” workflow below).

Trace-driven improvement (Instruments `.trace` provided)

Trigger whenever the user’s request references a .trace file. A target SwiftUI source file is optional — if given, cite specific lines; if not, recommend where to look based on view names and symbols the trace already reveals.

Full reference: references/trace-analysis.md. Summary of the composition pattern:

Scope the analysis. Ask yourself: does the user want the whole trace, or a slice?
- “focus on X / after X / between X and Y / during X” → resolve to a window first (see step 2).
- No scoping cue → analyse the whole trace.

Resolve a window (only if the user scoped). The parser exposes two discovery modes:

# Find a log that marks the start/end of the region of interest:
python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
    --list-logs --log-message-contains "loaded feed" --log-limit 5
# Or list os_signpost intervals (paired begin/end), filterable by name:
python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
    --list-signposts --signpost-name-contains "ImageDecode"

Both modes accept --window START_MS:END_MS to scope discovery. Pick the time_ms (for logs) or start_ms/end_ms (for signposts) that match the user’s description. Build a window like --window 10400:11700.

Run the main analysis (with or without --window):

python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
    --json-only --top 10 [--window START_MS:END_MS]

Interpret with references/trace-analysis.md — key diagnostics:
- main_running_coverage_pct inside each correlation (<25% = blocked; ≥75% = CPU-bound).
- swiftui-causes.top_sources reveals why updates keep happening — high-edge-count sources like UserDefaultObserver.send() or wide EnvironmentWriter entries are structural invalidation bugs. Fixing one often collapses many downstream hot views.
When a specific view shows as expensive, ask who’s invalidating it. Use --fanin-for "<view name>" to get the ranked list of source nodes driving the updates.
Optionally ground in source. If the user pointed at a file, read it and match view names / user-code symbols against identifiers there. If not, recommend which files to open based on the view names SwiftUI reported.
Return a prioritised plan. Cite evidence (coverage %, hot symbol, overlapping view, log timestamp, cause-graph edges) and route each recommendation to a Topic Router reference.
Only edit code if the user asked for edits.

Topic Router

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

Topic	When it applies	Reference
State management	Property wrapper choice, data flow design	`references/state-management.md`
View composition	Extracting subviews, container patterns	`references/view-structure.md`
Performance	Diagnosing hangs, hitches, excessive updates	Use the `swiftui-performance-audit` skill
Lists and ForEach	List rendering, identity, filtering	`references/list-patterns.md`
Layout	GeometryReader alternatives, layout containers	`references/layout-best-practices.md`
Sheets and navigation	Sheets, NavigationSplitView, Inspector	`references/sheet-navigation-patterns.md`
ScrollView	Programmatic scrolling, ScrollViewReader	`references/scroll-patterns.md`
Focus management	`@FocusState`, focusable views	`references/focus-patterns.md`
Animations (basics)	Implicit/explicit animations, timing	`references/animation-basics.md`
Animations (transitions)	View transitions, `matchedGeometryEffect`	`references/animation-transitions.md`
Animations (advanced)	Phase/keyframe animations, `@Animatable`	`references/animation-advanced.md`
Accessibility	VoiceOver, Dynamic Type, grouping, traits	`references/accessibility-patterns.md`
Swift Charts	Chart marks, axes, selection, styling	`references/charts.md`
Charts accessibility	Charts VoiceOver, Audio Graph	`references/charts-accessibility.md`
Image optimization	AsyncImage, downsampling, caching	`references/image-optimization.md`
Liquid Glass (iOS 26+)	Adopting or reviewing Liquid Glass	Use the `swiftui-liquid-glass` skill
macOS scenes	Settings, MenuBarExtra, multi-window	`references/macos-scenes.md`
macOS window styling	Toolbar styles, window sizing, Commands	`references/macos-window-styling.md`
macOS views	HSplitView, Table, AppKit interop	`references/macos-views.md`
Text patterns	Text initializer choice, localization	`references/text-patterns.md`
Deprecated API lookup	Checking if an API is deprecated	`references/latest-apis.md`
Instruments trace analysis	Given a `.trace` file to interpret	`references/trace-analysis.md`
Instruments trace recording	Asked to record a new trace	`references/trace-recording.md`

Correctness Checklist

These are hard rules – violations are always bugs:

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 (for reordering/refactoring an existing view file’s structure, DI, and Observation usage, use the swiftui-view-refactor skill instead)
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/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
references/text-patterns.md – Text initializer selection, verbatim vs localized
references/trace-analysis.md – Parse Instruments .trace files via scripts/analyze_trace.py; interpret main-thread coverage, high-severity SwiftUI updates, hitch narratives, and map findings back to source files
references/trace-recording.md – Record a new trace via scripts/record_trace.py: attach to a running app, launch one fresh, or capture a manually-stopped session; supports stop-file for agent-driven flows

Source: AvdLee/SwiftUI-Agent-Skill, adapted.