SwiftUI Views skill for Codex

Done well means: views are small value types driven by an @Observable model, state has exactly one owner, layout adapts from the smallest iPhone to iPad and the largest accessibility text size, every view has a #Preview, and the target builds without warnings under Swift 6 strict concurrency.

Inspect first

cat AGENTS.md 2>/dev/null
xcodebuild -list                                   # schemes and targets
grep -rE 'IPHONEOS_DEPLOYMENT_TARGET|SWIFT_VERSION' *.xcodeproj/project.pbxproj | sort -u
grep -rlE 'ObservableObject|@Observable' --include='*.swift' . | head

The deployment target decides the toolset: @Observable needs iOS 17 / macOS 14; @Entry, the Tab type and mesh gradients need iOS 18; Liquid Glass APIs (glassEffect) need iOS 26. Do not introduce APIs above the target without if #available and a fallback.

State: who owns what

Data	Declare as	Notes
Value owned by this view (toggle, text)	@State private var	Private; initial value used once
Reference model owned by this view	@State private var model = Model()	Model is @Observable
Model passed in, need bindings	@Bindable var model: Model	$model.name
Model passed in, read only	let model: Model	Observation tracks reads automatically
Shared through the tree	.environment(model) / @Environment(Model.self)	Crashes if missing; inject at the root and in previews
Two-way value from parent	@Binding var isOn: Bool
Legacy ObservableObject	@StateObject / @ObservedObject	Migrate when touched

import Observation
import SwiftUI

@MainActor @Observable
final class ProfileModel {
    var name = ""
    var isSaving = false
    private(set) var error: String?
    @ObservationIgnored private let api: ProfileAPI

    init(api: ProfileAPI) { self.api = api }

    func save() async {
        isSaving = true
        defer { isSaving = false }
        do { try await api.update(name: name) } catch { self.error = error.localizedDescription }
    }
}

struct ProfileView: View {
    @Bindable var model: ProfileModel

    var body: some View {
        Form {
            TextField("Name", text: $model.name)
                .textContentType(.name)
            if let error = model.error {
                Text(error).foregroundStyle(.red)
            }
            Button("Save") { Task { await model.save() } }
                .disabled(model.isSaving || model.name.isEmpty)
        }
    }
}

#Preview {
    ProfileView(model: ProfileModel(api: .preview))
}

Migration from ObservableObject: drop the conformance and @Published, add @Observable, replace @StateObject with @State, @ObservedObject with a plain let or @Bindable, and @EnvironmentObject with @Environment(Type.self).

Layout

• Compose with VStack/HStack/ZStack, Grid for aligned rows and columns, LazyVStack/LazyVGrid inside ScrollView for long content, List when you want platform list behaviour (swipe actions, separators, edit mode).
• Adapt instead of measuring: ViewThatFits picks the first child that fits; @Environment(\.horizontalSizeClass) switches compact vs regular layouts; containerRelativeFrame sizes relative to the scroll container.
• Avoid GeometryReader for ordinary layout; it takes all offered space and breaks intrinsic sizing. Use it (or onGeometryChange) only to read a size you truly need.
• Write a custom Layout when stacks cannot express it (flow/tag layouts).
• Use .frame(maxWidth: .infinity, alignment: .leading) rather than Spacer() chains for alignment.

Identity and performance

• ForEach needs stable identity: Identifiable models with persistent IDs. Never id: \.self on mutable values or array indices for dynamic data.
• Conditional if/else creates two different views; toggling destroys state. To change appearance, use a modifier with a conditional value (.opacity(isOn ? 1 : 0)).
• Avoid AnyView; use @ViewBuilder or some View returns.
• Extract subviews so Observation tracks reads per view; a giant body re-renders everything when any read property changes.
• Debug re-renders with let _ = Self._printChanges() at the top of body (debug only; remove before committing).
• Keep body free of work: no formatting of large collections, no sorting, no I/O. Precompute in the model.

Async work

.task(id: query) {                  // cancels and restarts when query changes
    try? await Task.sleep(for: .milliseconds(300))
    guard !Task.isCancelled else { return }
    await model.search(query)
}

• Prefer .task over onAppear { Task { } }: it is cancelled automatically when the view disappears.
• onChange(of:initial:_:) takes the two-parameter closure { old, new in } on iOS 17+.
• Views are @MainActor. Keep models that drive UI on the main actor and push heavy work into nonisolated functions or separate actors.

Accessibility

• Use semantic fonts (.font(.body), .headline) so Dynamic Type works; for custom fonts use .font(.custom("Inter", size: 17, relativeTo: .body)).
• Test at the largest accessibility size: stacks that overflow should switch axis via ViewThatFits or dynamicTypeSize checks.
• Icon-only buttons need labels: Button("Delete", systemImage: "trash") { } with .labelStyle(.iconOnly) keeps a VoiceOver label.
• Group related elements with .accessibilityElement(children: .combine).
• Touch targets at least 44x44 pt (.contentShape(Rectangle()) plus padding).

Gotchas

• @State var model: Model initialised from an init parameter is only read on first creation; later parent updates are ignored. Pass it as let/@Bindable instead.
• @Environment(Model.self) without an injected value crashes at runtime, including in previews. Inject in every #Preview.
• Do not mark @Observable properties with @Published; mixing the systems silently breaks tracking.
• Computed properties on @Observable classes are tracked through the stored properties they read; caching them in @ObservationIgnored storage stops updates.
• Text truncation in other languages: avoid fixed widths; check with a pseudolanguage (scheme option “Double-Length Pseudolanguage”).

Verification

xcodebuild -scheme App -destination 'platform=iOS Simulator,name=iPhone 17' \
  -derivedDataPath build/DerivedData build test | xcbeautify   # xcbeautify optional

Use -derivedDataPath inside the workspace so the build works under a sandbox that blocks writes to ~/Library. Run xcrun simctl list devices available if the simulator name does not exist. Then check each changed view in previews or the simulator: light and dark, smallest and largest Dynamic Type, iPhone SE width and iPad, VoiceOver labels via Accessibility Inspector. Snapshot tests (swift-snapshot-testing) lock layouts once agreed.

Report template

**Target:** iOS 17.0, Swift 6 language mode
**Changed:** ProfileModel migrated to @Observable; ProfileView split into header and form
**Checks:** build + 31 tests green; previews light/dark, XXXL text, iPhone SE, iPad
**Notes:** _printChanges showed list rows re-rendering on every keystroke; fixed by extracting RowView