Developer Guides
iOS 26/27 and on-device AI guides for problems tutorials skip.
Production guides for Foundation Models, Private Cloud Compute, Core AI, App Intents, Liquid Glass, SpeechAnalyzer, Swift 6 strict concurrency, and on-device AI failure modes. The focus is what broke, what to do, and how to ship the fix.
Start with Foundation Models errors, availability gating, Private Cloud Compute routing, Core AI model deployment, Liquid Glass migration, or Swift 6 migration pain.
routes
/guides/foundation-models/*
schema
TechArticle + ItemList
crawl
sitemap + llms.txt
style
what broke + production fix
13 guides
Making Your App Siri-Actionable in iOS 27: App Intents as the Entry Point, Not an Afterthought
Why App Intents is now the gateway between your app and Siri, Spotlight, Shortcuts, and Widgets: defining intents and entities, using built-in domain schemas, foreground vs background execution, donations, and snippets for visual results.
Implementation Notes
- ~/ What broke: Siri, Spotlight, Shortcuts, and Widgets cannot act on app features that are not modeled as intents and entities.
- ~/ What to do: Model app actions as App Intents, expose content as App Entities, donate usage, and return snippets for visual results.
- ~/ Requires: iOS 27+, SwiftUI, App Intents framework
Fix exceededContextWindowSize in Foundation Models: Production Recovery Pattern
How to handle the Foundation Models exceededContextWindowSize error in a shipped app: why the catch block is too late, the transcript-summarization recovery pattern, and the iOS 26.4 token-count API for pre-flight checks.
Implementation Notes
- ~/ What broke: The session transcript filled the on-device model context window.
- ~/ What to do: Trim session history, summarize state, and recover without losing the user's current task.
- ~/ Requires: iOS 26+, Foundation Models, async/await
Fixing guardrailViolation in Foundation Models: False Positives, the Locale Trap, and Fallbacks
Why Foundation Models throws guardrailViolation on harmless prompts, the Siri/macOS language mismatch that blocks model downloads entirely, and a production fallback strategy for safety-rejected generations.
Implementation Notes
- ~/ What broke: Harmless prompts can look unsafe when model assets, locale, or fallback state are wrong.
- ~/ What to do: Add locale checks, user-safe fallbacks, and retry copy that does not hide real safety failures.
- ~/ Requires: iOS 26+, Foundation Models, Xcode 26
Foundation Models GenerationError: Complete Handling Reference for Production iOS Apps
A complete reference for every LanguageModelSession.GenerationError case: what each means, which are recoverable, what to retry, and what user-facing copy to show. Includes the cryptic 'error 4' decode.
Implementation Notes
- ~/ What broke: Opaque Foundation Models errors reached users as generic failures.
- ~/ What to do: Map Foundation Models failures to deterministic UI states and useful recovery paths.
- ~/ Requires: iOS 26+, Foundation Models, async/await
Persisting Foundation Models Output with SwiftData: Storing Generated Structs Safely
How to persist @Generable output with SwiftData: separating generation types from model types, handling schema drift when the AI shape changes, CloudKit sync considerations, and versioning generated content.
Implementation Notes
- ~/ What broke: Generated output was persisted before it was validated and versioned.
- ~/ What to do: Validate, version, and persist generated output only after the model response is complete.
- ~/ Requires: iOS 26+, Foundation Models, SwiftData
Routing Foundation Models Through Private Cloud Compute: The LanguageModel Protocol in iOS 27
How the LanguageModel protocol in iOS 27 lets one session API run on-device or on Private Cloud Compute: 32K context and extended reasoning via a one-line change, availability and quota handling, network fallback, and when PCC is worth it.
Implementation Notes
- ~/ What broke: Teams treat PCC as a default upgrade instead of a measured enhancement over the on-device floor.
- ~/ What to do: Route through the LanguageModel protocol with availability, network, quota, and reasoning-level gates.
- ~/ Requires: iOS 27+, Foundation Models, async/await
Streaming @Generable Snapshots into SwiftUI Without Flicker
How to stream partial @Generable output into SwiftUI cleanly: consuming the snapshot sequence, animating progressive fills without flicker or layout jumps, and handling partial-to-final transitions.
Implementation Notes
- ~/ What broke: Streaming structured output flickers and jumps in SwiftUI.
- ~/ What to do: Render partial snapshots with stable identity and a final-state handoff.
- ~/ Requires: iOS 26+, Foundation Models, SwiftUI, async/await
SystemLanguageModel Availability: Gating On-Device AI for Every Apple Device
How to gate Foundation Models features correctly: checking SystemLanguageModel.availability, handling the device-eligibility matrix, and designing graceful-degradation UI for the large share of devices that can't run the model.
Implementation Notes
- ~/ What broke: The AI feature assumed the system language model was always ready.
- ~/ What to do: Gate features on SystemLanguageModel availability before showing AI entry points.
- ~/ Requires: iOS 26+, Foundation Models, SwiftUI
Tool Calling in Foundation Models: Wiring Real Tools (HealthKit, MapKit) Not Toy Examples
How to implement Foundation Models tool calling with real system frameworks: defining a Tool, wiring it to HealthKit or MapKit, handling permission and failure inside tool calls, and keeping the model honest.
Implementation Notes
- ~/ What broke: Toy tool examples ignore permissions, failure, and real data.
- ~/ What to do: Wrap real tools with permission gates, typed errors, and observable audit trails.
- ~/ Requires: iOS 26+, Foundation Models, async/await
Core AI in iOS 27: Running Your Own Models On-Device Alongside Foundation Models
What Core AI is in iOS 27, how it differs from Foundation Models and Core ML, the .aimodel format and conversion toolchain (Core AI Optimization, PyTorch extensions, MLX), and how AIModel / AIModelAsset / InferenceFunction fit together.
Implementation Notes
- ~/ What broke: Custom neural-network model work gets conflated with Foundation Models prompts or old Core ML deployment paths.
- ~/ What to do: Use Core AI only for owned neural networks, then isolate conversion, specialization, caching, and profiling paths.
- ~/ Requires: iOS 27+, Apple silicon, model conversion (Python), Swift
Migrating from SFSpeechRecognizer to SpeechAnalyzer: On-Device Transcription in iOS 26
A practical migration guide from the deprecated-feeling SFSpeechRecognizer to the new SpeechAnalyzer / SpeechTranscriber APIs: on-device transcription, async streaming results, and what changes architecturally.
Implementation Notes
- ~/ What broke: Callback-era speech recognition patterns do not map cleanly to iOS 26.
- ~/ What to do: Move from delegate callbacks to async transcription flows with explicit permission states.
- ~/ Requires: iOS 26+, Swift concurrency, audio basics
Adopting Liquid Glass in SwiftUI: glassEffect, Migration Pitfalls, and When It Breaks
A production look at adopting Liquid Glass in SwiftUI: applying glassEffect correctly, the migration pitfalls that break custom UI, performance and legibility caveats, and when not to use it.
Implementation Notes
- ~/ What broke: Custom chrome fights the new iOS 26 visual system.
- ~/ What to do: Adopt glassEffect around native hierarchy boundaries instead of repainting every surface.
- ~/ Requires: iOS 26+, SwiftUI
Migrating a Real App to Swift 6 Strict Concurrency: The Sendable and @MainActor Errors You'll Hit
A pragmatic guide to migrating a shipped app to Swift 6 strict concurrency: decoding the real Sendable and @MainActor data-race errors, the migration order that minimizes pain, and the escape hatches that are actually safe.
Implementation Notes
- ~/ What broke: Swift 6 turned hidden data races into compiler errors.
- ~/ What to do: Separate UI state, actors, Sendable models, and legacy adapters into migration slices.
- ~/ Requires: Swift concurrency basics, async/await, an existing codebase