SwiftUI

Shape the interface around SwiftUI's ownership, identity, and environment rather than reproducing an imperative view hierarchy. Preserve the product's existing architecture and deployment targets unless the task changes them.

For an authorized build or fix, implement and test the workflow below. For a plan or review, leave the product unchanged and turn its implementation and test steps into exact proposed changes, findings, and checks.

Workflow

1. Inspect the affected scene, views, models, deployment targets, and existing design system. Trace each mutable value to its source of truth and each user action to the code that owns its effect.
2. Read only the references needed for the task:
   • Model the Domain for state ownership and domain shapes; Boundary Discipline for interface boundaries; and Make Operations Idempotent when effects can overlap, repeat, or outlive their view. Apply these through SwiftUI's state, identity, and lifecycle rules below.
   • Choosing SwiftUI or UIKit when the framework is not fixed or the work could introduce a framework boundary. If UIKit owns the affected surface, continue with uikit and end this workflow. For a hybrid, name the boundary and continue here only for the SwiftUI-owned side.
   • State and data flow for ownership, Observation, bindings, environment values, or editable drafts.
   • Composition and identity for view boundaries, collection identity, update scope, or restructuring a large view.
   • Navigation and presentation for stacks, split views, routes, sheets, dialogs, or restoration.
   • SDK 27 migration when an Xcode 27 build introduces @State, result-builder, or preview diagnostics.
   • Collection interactions for reordering or swipe actions in lists, stacks, grids, or custom layouts.
   • Toolbars for overflow, pinned items, visibility priority, or minimization behavior.
   • Remote images for AsyncImage loading, request policy, session choice, or caching.
   • Document apps for creating or migrating a document-based app, viewer, reader, or writer.
   • Materials and Liquid Glass when adopting current platform materials or reviewing custom glass effects.
3. Make the source of truth and view identity explicit before changing layout. Give each view only the values, bindings, and actions it needs. Keep durable storage and business rules outside transient view state.
4. Prefer native containers and controls for the target platform. Add a UIKit or AppKit bridge at a deliberate boundary when SwiftUI lacks the required behavior; keep lifecycle and ownership on one side of that boundary.
5. For interactive components, give immediate feedback and keep loading, empty, disabled, error, and overflow states close to the action or content they describe. Prevent interrupted or repeated async work from letting an older result overwrite the current state. Prefer platform controls and strong defaults over extra options; preserve valid activation and cancellation. When sizing a button, inspect its visible bounds and hit region after styling; compare the hit region, not the label frame, with the platform's button guidance.
6. Preserve useful accessibility semantics. Expose the control's name, value, state, and actions, and keep focus and announcements aligned with the task and reading order rather than an incidental view hierarchy. Announce visible async status, validation, and errors when focus does not move and the change would otherwise be missed.
7. Build the affected targets and exercise main, edge-state, interruption, and repeated-input transitions. When behavior or accessibility is in scope, exercise the supported touch, pointer, keyboard, focus, announcement, and VoiceOver reading paths. Use verify for visual or interactive acceptance checks. Use animate for motion design, ios-haptics for iOS tactile feedback, ui-design for visual hierarchy and token-system work, and diagnosing-bugs when a failure or performance regression needs investigation.

After performance diagnosis identifies the bottleneck, use the data-flow and composition guidance here to narrow invalidation or reduce body work without changing behavior.