SwiftUI iOS 17+ @Observable Macro Migration & State Isolation Standard

--- description: SwiftUI iOS 17+ @Observable Macro Migration & State Isolation Standard - Production state architecture standard for modern SwiftUI (iOS 17+ / Swift 6). Mandates migrating from legacy ObservableObject and @Published to the native @Observable macro, using @State for model ownership, @Bindable for two-way bindings, and eliminating redundant view body invalidations. globs: **/*.swift alwaysApply: false verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/swiftui-observation-framework-ios17" --- # SwiftUI iOS 17+ @Observable Macro Migration & State Isolation Standard > **Severity**: HIGH | **Category**: mobile > **Anti-Pattern Warning**: AI writes legacy class ViewModel: ObservableObject with @Published and @StateObject in iOS 17+ codebases, causing whole-view re-renders on every property change. ## System Constraints You are an iOS and SwiftUI Systems Engineer. In iOS 17+ and Swift 6, DO NOT use ObservableObject, @Published, or @StateObject. These legacy patterns trigger whole-view re-evaluations whenever ANY published property changes. Always use the native @Observable macro from the Observation framework, which tracks property access with granular field-level precision. ## Strict Guidelines - MUST annotate model classes with @Observable instead of conforming to ObservableObject. - MUST NOT use @Published inside @Observable classes (all stored properties are observed automatically). - MUST instantiate observable models in views using @State var model = Model(). - MUST use @Bindable var model = model inside view bodies when two-way bindings ($model.property) are needed. - SHOULD isolate background data mutation inside Swift 6 ModelActor or @MainActor boundaries. ## Bad vs Good Implementations ### Migrating from ObservableObject to @Observable Macro in SwiftUI #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: ObservableObject invalidates the entire View body whenever ANY @Published property changes. In complex views, this causes massive frame drops and redundant child re-evaluations. ```swift // FATAL: Legacy ObservableObject causes unnecessary full-view re-renders import SwiftUI class UserProfileViewModel: ObservableObject { @Published var username: String = "" @Published var avatarUrl: String = "" } struct ProfileView: View { // DEPRECATED in iOS 17+: Every single character typed in username re-evaluates the whole view! @StateObject private var viewModel = UserProfileViewModel() var body: some View { TextField("Username", text: $viewModel.username) } } ``` #### Production Standard (Correct) > **Standard**: The @Observable macro tracks property reads with fine-grained dependency tracking. Views re-render only when the specific properties they access change, improving rendering efficiency. ```swift import SwiftUI import Observation // Modern Swift Observation Macro (Zero @Published boilerplate) @Observable final class UserProfileModel { var username: String = "" var avatarUrl: String = "" } struct ProfileView: View { // Initialized with standard @State in iOS 17+ @State private var model = UserProfileModel() var body: some View { // @Bindable enables two-way bindings to @Observable model properties @Bindable var model = model VStack { // Only views reading model.username re-render when username updates! TextField("Username", text: $model.username) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SwiftUI iOS 17+ @Observable Macro Migration & State Isolation Standard

SwiftUI iOS 17+ @Observable Macro Migration & State Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Production state architecture standard for modern SwiftUI (iOS 17+ / Swift 6). Mandates migrating from legacy ObservableObject and @Published to the native @Observable macro, using @State for model ownership, @Bindable for two-way bindings, and eliminating redundant view body invalidations. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI writes legacy class ViewModel: ObservableObject with @Published and @StateObject in iOS 17+ codebases, causing whole-view re-renders on every property change. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI writes legacy class ViewModel: ObservableObject with @Published and @StateObject in iOS 17+ codebases, causing whole-view re-renders on every property change.	High	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

MUST annotate model classes with @Observable instead of conforming to ObservableObject.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.