Help us improve
Share bugs, ideas, or general feedback.
From swiftui-expert
Provides SwiftUI expertise for writing, reviewing, and refactoring iOS/macOS UI code. Covers state management, view composition, performance, and Instruments trace recording/analysis.
npx claudepluginhub avdlee/swiftui-agent-skill --plugin swiftui-expertHow this skill is triggered — by the user, by Claude, or both
Slash command
/swiftui-expert:swiftui-expert-skillThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
- Consult `references/latest-apis.md` at the start of every task to avoid deprecated APIs
references/accessibility-patterns.mdreferences/animation-advanced.mdreferences/animation-basics.mdreferences/animation-transitions.mdreferences/charts-accessibility.mdreferences/charts.mdreferences/focus-patterns.mdreferences/image-optimization.mdreferences/latest-apis.mdreferences/layout-best-practices.mdreferences/liquid-glass.mdreferences/list-patterns.mdreferences/macos-scenes.mdreferences/macos-views.mdreferences/macos-window-styling.mdreferences/performance-patterns.mdreferences/previews.mdreferences/scroll-patterns.mdreferences/sheet-navigation-patterns.mdreferences/state-management.mdAudits SwiftUI performance via code review for issues like slow rendering, janky scrolling, high CPU/memory, excessive updates, and guides Instruments profiling.
Audits SwiftUI performance issues from code review and profiling evidence: invalidation storms, unstable identity, layout thrash, and main-thread work. Useful for slow rendering, janky scrolling, or high CPU.
Audits SwiftUI runtime performance, identifies root causes of slow rendering, janky scrolling, excessive view updates, and guides remediation using Instruments profiling.
Share bugs, ideas, or general feedback.
references/latest-apis.md at the start of every task to avoid deprecated APIsreferences/liquid-glass.md)#available gating with sensible fallbacks for version-specific APIsreferences/latest-apis.md)#available gating and fallback paths for iOS 26+ featuresreferences/latest-apis.mdUIImage(data:) is encountered (optional optimization, see references/image-optimization.md)Button for all tappable elements; add accessibility grouping and labels#available and provide fallbacksTrigger when the user asks to "record a trace", "profile the app", "capture a session", etc. Full reference: references/trace-recording.md.
python3 "${SKILL_DIR}/scripts/record_trace.py" --list-devices
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.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.touch /tmp/stop-trace. The script cleanly SIGINTs xctrace and waits up to 60s for finalisation..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:
# 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.--window):
python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
--json-only --top 10 [--window START_MS:END_MS]
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.--fanin-for "<view name>" to get the ranked list of source nodes driving the updates.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 |
| Text patterns | references/text-patterns.md |
| Deprecated API lookup | references/latest-apis.md |
| Previews | references/previews.md |
| Instruments trace analysis | references/trace-analysis.md |
| Instruments trace recording | references/trace-recording.md |
These are hard rules -- violations are always bugs:
@State properties are private@Binding only where a child modifies parent state@State or @StateObject (they ignore updates)@StateObject for view-owned objects; @ObservedObject for injected@State with @Observable; @Bindable for injected observables needing bindingsForEach uses stable identity (never .indices for dynamic content)ForEach element.animation(_:value:) always includes the value parameter@FocusState properties are private@FocusState writes inside tap gesture handlers on .focusable() views#available and fallback providedimport Charts present in files using chart typesreferences/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 migrationreferences/view-structure.md -- View extraction, container patterns, @ViewBuilderreferences/performance-patterns.md -- Hot-path optimization, update control, _logChanges()references/list-patterns.md -- ForEach identity, Table (iOS 16+), inline filtering pitfallsreferences/layout-best-practices.md -- Layout patterns, GeometryReader alternativesreferences/accessibility-patterns.md -- VoiceOver, Dynamic Type, grouping, traitsreferences/animation-basics.md -- Implicit/explicit animations, timing, performancereferences/animation-transitions.md -- View transitions, matchedGeometryEffect, Animatablereferences/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 strategiesreferences/sheet-navigation-patterns.md -- Sheets, NavigationSplitView, Inspectorreferences/scroll-patterns.md -- ScrollViewReader, programmatic scrollingreferences/focus-patterns.md -- Focus state, focusable views, focused values, default focus, common pitfallsreferences/image-optimization.md -- AsyncImage, downsampling, cachingreferences/liquid-glass.md -- iOS 26+ Liquid Glass effects and fallback patternsreferences/macos-scenes.md -- Settings, MenuBarExtra, WindowGroup, multi-windowreferences/macos-window-styling.md -- Toolbar styles, window sizing, Commandsreferences/macos-views.md -- HSplitView, Table, PasteButton, AppKit interopreferences/previews.md -- #Preview macro, @Previewable (iOS 18+), preview traits, mock data patterns for self-contained previewsreferences/text-patterns.md -- Text initializer selection, verbatim vs localizedreferences/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 filesreferences/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