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

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

1. 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:

   python3 "${SKILL_DIR}/scripts/record_trace.py" --list-devices
   

2. 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

   .
3. 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:

   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.
4. 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.
5. 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

Full reference:

references/trace-analysis.md

1. 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.
2. 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

   .
3. 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]
   

4. 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.
5. 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.
6. 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.
7. 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.
8. Only edit code if the user asked for edits.

Topic Router

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

references/state-management.md

references/view-structure.md

references/performance-patterns.md

references/list-patterns.md

references/layout-best-practices.md

references/sheet-navigation-patterns.md

references/scroll-patterns.md

references/focus-patterns.md

references/animation-basics.md

references/animation-transitions.md

references/animation-advanced.md

references/accessibility-patterns.md

references/charts.md

references/charts-accessibility.md

references/image-optimization.md

references/liquid-glass.md

references/macos-scenes.md

references/macos-window-styling.md

references/macos-views.md

references/text-patterns.md

references/latest-apis.md

references/trace-analysis.md

references/trace-recording.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

• 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