From swiftui-expert
Writes, reviews, improves SwiftUI code for state management, view composition, performance, macOS APIs, iOS 26+ Liquid Glass. Analyzes Xcode Instruments .trace files; records new traces via record_trace.py to diagnose hangs, hitches, CPU hotspots.
npx claudepluginhub avdlee/swiftui-agent-skill --plugin swiftui-expertThis skill uses the workspace's default tool permissions.
- 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/scroll-patterns.mdreferences/sheet-navigation-patterns.mdreferences/state-management.mdreferences/text-patterns.mdGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
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 |
| 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/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