---
name: native-ios-core
description: "Shared reference for the native-iOS cluster: the iOS 26 / Swift 6.2 / Xcode 26 baseline, availability-gating discipline for the new frameworks, the data-race-safety (actor isolation + Sendable) model, and shared SwiftUI conventions. USE WHEN adopting Swift 6.2 concurrency, gating an iOS 26-only API, or choosing a state/persistence pattern — the rules every native-iOS spoke shares."
cluster: native-ios
version: 1.0.0
---

# Native iOS Core

Shared model for the `native-ios` cluster. The concurrency, SwiftUI, persistence, AI, and design
spokes all depend on the same baseline and the same safety rules — keep them consistent here so no
spoke contradicts another.

## 1. The baseline (this cluster's defining decision)

Everything is written for **one toolchain line**:

```
Xcode 26 ──compiles──> Swift 6.2 ──targets──> iOS 26 / macOS 26 (with graceful fallback below)
```

The flagship capabilities the cluster exists to teach — **Approachable Concurrency**, **Liquid
Glass**, and **on-device FoundationModels** — only exist on this line. So the first question for
any task is *"what's the deployment target, and is this API available there?"* — not *"how do I
call it?"*. Get the baseline right and the spokes compose; get it wrong and they conflict.

## 2. Availability gating (non-negotiable)

A higher SDK does **not** mean every device can run the API. Gate, don't assume:

- **Compile-time / OS gate** — wrap iOS 26-only UI (Liquid Glass, newest SwiftUI) in `if #available(iOS 26, *)` with a real pre-26 branch. → `liquid-glass-design`
- **Runtime capability gate** — on-device AI is gated by hardware + user settings, not just OS. Always switch on `SystemLanguageModel.default.availability` (`.available` / `.unavailable(...)`) before opening a session. → `foundation-models-on-device`

**Rule:** never raise the whole app's minimum deployment target just to use one new affordance — gate the affordance and keep a fallback.

## 3. Data-race safety model (Swift 6.2)

Concurrency is **isolated-by-default**; you opt *into* parallelism, not out of it.

- Async code **stays on the calling actor** by default (no implicit background hop). Offload explicitly with `@concurrent`. → `swift-concurrency-6-2`
- **MainActor** is the default isolation for UI types; non-isolated protocols are satisfied via **isolated conformances**.
- Cross-isolation values must be **`Sendable`**; the compiler enforces it.
- **Actors** serialize access to shared mutable state — use them for persistence/caches instead of locks or `DispatchQueue`. → `swift-actor-persistence`
- Abstract I/O (file system, network, iCloud) behind small **`Sendable` protocols** so it's mockable and the isolation stays clean. → `swift-protocol-di-testing`

## 4. Shared SwiftUI & architecture conventions

- State: **`@Observable`** (Observation framework) over `ObservableObject`/`@Published` — property-level change tracking, fewer re-renders. → `swiftui-patterns`
- Pick the **narrowest** property wrapper that fits (`@State` → `@Binding` → `@Bindable` → `@Environment`).
- Inject dependencies via protocols (not concretes) so views are previewable and testable. → `swift-protocol-di-testing`
- Structured AI output uses **`@Generable`** types, not hand-parsed strings. → `foundation-models-on-device`
- Icons ship as **asset-catalog imagesets** (1x/2x/3x), generated to match existing project style. → `ios-icon-gen`

## 5. Version / tooling matrix

| Concern | Target | Spoke | Notes |
|---|---|---|---|
| Toolchain | Xcode 26 | (all) | required for Swift 6.2 + iOS 26 SDK |
| Language / concurrency | Swift 6.2 | `swift-concurrency-6-2` | Approachable Concurrency build setting on |
| UI framework | SwiftUI (Observation) | `swiftui-patterns` | `@Observable`, `NavigationStack` |
| Persistence | Swift 5.5+ actors | `swift-actor-persistence` | works back to 5.5; written for 6.2 isolation |
| Testing | Swift Testing | `swift-protocol-di-testing` | `@Test`/`#expect`, protocol mocks |
| On-device AI | iOS 26+ FoundationModels | `foundation-models-on-device` | availability-gated, hardware-dependent |
| Design system | iOS 26+ Liquid Glass | `liquid-glass-design` | SwiftUI / UIKit / WidgetKit |
| Assets | Xcode asset catalog | `ios-icon-gen` | SF Symbols (macOS) or Iconify (network) |

## 6. Shared guardrails

- **Baseline first**: confirm deployment target before reaching for an iOS 26 API.
- **Gate every new API**: `if #available` for OS features, `.availability` for on-device AI — always with a fallback.
- **Don't widen the deployment target silently** to use one affordance.
- **Isolated-by-default**: keep data-race safety; offload with `@concurrent`, share via `Sendable`, serialize state with actors — never ad-hoc background dispatch.
- **`@Observable` over `ObservableObject`**; narrowest property wrapper that works.
- **Protocol-seam I/O**: external dependencies behind `Sendable` protocols so tests stay deterministic.
- Native Swift vs cross-platform: pick this cluster for the newest first-party frameworks (Liquid Glass, on-device AI) and full platform fidelity; if the app must also ship Android/web from one codebase, weigh a cross-platform stack instead.