AGENTS.ios.md — iOS apps: SwiftUI / UIKit / Xcode

Additive to ../AGENTS.md and AGENTS.swift.md. iOS app rules only.

Build and check

swiftformat --lint . && swiftlint --strict
xcodebuild test -scheme App -destination 'platform=iOS Simulator,name=iPhone 16'

Views are small and take their data in. No networking in a body.
New design system components need a #Preview and must use tokens from the shared style layer, not literal colors or spacings.
@StateObject at ownership, @ObservedObject when passed in. Getting this backwards causes the bugs nobody can reproduce.
For @Observable types (iOS 17+): @State at ownership, a plain property when passed in, @Bindable when the child needs bindings.
Async work tied to a view’s lifetime goes in .task {}, which cancels on disappear. Not onAppear { Task { … } }.

A view controller owns layout and view lifecycle. Networking, persistence and business logic live in a view model or service it is handed.
No new storyboards. New screens are programmatic UIKit, or SwiftUI hosted in a UIHostingController. Existing storyboards stay until their screen is rebuilt.
Auto Layout via NSLayoutConstraint.activate, with translatesAutoresizingMaskIntoConstraints = false. No frame math in layoutSubviews without a measured reason.
Escaping closures that can outlive the controller capture [weak self]. Delegates are weak.
New table and collection views use diffable data sources, not reloadData() plus index bookkeeping.
Keep the bridges thin: UIHostingController for SwiftUI in UIKit, UIViewRepresentable / UIViewControllerRepresentable for UIKit in SwiftUI.

Build settings live in .xcconfig files, not the project editor. .xcconfig files are Kitchen.
Swift rules, dependencies and testing are in AGENTS.swift.md.

Massive view files (>300 lines) that should be decomposed.
Massive view controllers: URLSession or persistence calls in a UIViewController.