SwiftUI Expert Skill

A soft-deprecated API is marked as deprecated in the SDK headers using a placeholder version (100000.0) to suppress compiler warnings. These APIs still compile and function correctly, but they signal that they should not be used in new code.

Common examples include:

• NavigationView (use NavigationStack or NavigationSplitView instead)
• ActionSheet / Alert (use .confirmationDialog or .alert modifiers instead)
• MagnificationGesture (use MagnifyGesture instead)
• PresentationMode (use \.dismiss instead)

Treat these APIs as informational rather than urgent errors.

Select a scrolling implementation based on your target iOS version and requirements:

• iOS 18+: Use onScrollGeometryChange(for:of:action:) to observe scroll geometry and scrollPosition(_:) with ScrollPosition for flexible scrolling (identity, offset, or edge).
• iOS 17+: Use scrollPosition(id:) with an optional ID binding for simple identity-based scrolling.
• Legacy/Proxy-based: Use ScrollViewReader when you need proxy-based programmatic scrolling (e.g., scroll-to-top/bottom) or need to support versions earlier than iOS 17.

Use lazy containers like LazyVStack instead of standard VStack inside a ScrollView to ensure views are created on demand rather than all at once.

// GOOD - creates views on demand
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ExpensiveRow(item: item)
        }
    }
}

Sheets should manage their own dismissal and actions internally using @Environment(\.dismiss). Avoid passing onSave or onCancel closures from the parent view to prevent callback prop-drilling and improve reusability.

struct EditItemSheet: View {
    @Environment(\.dismiss) private var dismiss
    let item: Item
    @State private var name: String

    init(item: Item) {
        self.item = item
        _name = State(initialValue: item.name)
    }

    var body: some View {
        NavigationStack {
            Form { TextField("Name", text: $name) }
                .navigationTitle("Edit Item")
                .toolbar {
                    ToolbarItem(placement: .cancellationAction) { Button("Cancel") { dismiss() } }
                    ToolbarItem(placement: .confirmationAction) { Button("Save") { /* save and dismiss */ } }
                }
        }
    }
}

You can install this skill using a single command via the skills.sh platform. This is the quickest way to add the skill to an AI agent that supports the Agent Skills open format.

npx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill

Custom views should own their static containers (like an HStack for a header) so the caller doesn't have to. However, custom views should NOT own lazy or repeatable containers (like LazyVStack or List); those should be owned by the caller to allow for proper list management and performance.

// Good - owns static container
struct HeaderView: View {
    var body: some View {
        HStack {
            Image(systemName: "star")
            Text("Title")
            Spacer()
        }
    }
}

// Good - caller owns lazy container
struct FeedView: View {
    let items: [Item]
    
    var body: some View {
        LazyVStack {
            ForEach(items) { item in
                ItemRow(item: item)
            }
        }
    }
}

To improve performance and reduce memory usage when rendering large collections, use lazy containers like LazyVStack, LazyHStack, LazyVGrid, or LazyHGrid. These containers only load views as they appear on the screen.

struct ContentView: View {
    let items = Array(0..<1000)

    var body: some View {
        ScrollView {
            LazyVStack {
                ForEach(items, id: \.self) { item in
                    Text("Item \(item)")
                }
            }
        }
    }
}

Use the @Previewable macro to define dynamic properties (like @State) directly within a #Preview block.

#Preview {
    @Previewable @State var isOn = false
    Toggle("Setting", isOn: $isOn)
}

Because chart modifiers like .chartXSelection change the return type of the Chart view, you cannot conditionally apply them using a standard if #available block inside a single chain. Instead, you must duplicate the entire Chart implementation to provide fallbacks for older iOS versions.

API Availability Breakdown

• iOS 16+: Core Chart types (BarMark, LineMark, etc.), ChartProxy, chartOverlay, chartBackground.
• iOS 17+: SectorMark, selection APIs (chartXSelection, chartYSelection, chartAngleSelection), scrolling APIs (chartScrollableAxes, chartXVisibleDomain), and chartGesture.
• iOS 18+: Plot types (AreaPlot, BarPlot, LinePlot, PointPlot, RectanglePlot, RulePlot, SectorPlot) and function plotting.
• iOS 26+: Chart3D, SurfacePlot, Z-axis marks, and 3D camera/pose APIs.

To identify performance issues like main-thread coverage, high-severity SwiftUI updates, or hitch narratives, use the trace analysis script. This allows you to map performance findings directly back to your source files.

Use scripts/analyze_trace.py to parse Instruments .trace files.