|
| 1 | +--- |
| 2 | +name: ios-app-intents |
| 3 | +description: Design App Intents, app entities, and App Shortcuts for iOS system surfaces. Use when exposing app actions or content to Shortcuts, Siri, Spotlight, widgets, or controls. |
| 4 | +--- |
| 5 | + |
| 6 | +# iOS App Intents |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +Expose the smallest useful action and entity surface to the system. Start with the verbs and objects people would actually want outside the app, then implement a narrow App Intents layer that can deep-link or hand off cleanly into the main app when needed. |
| 11 | + |
| 12 | +Read these references as needed: |
| 13 | + |
| 14 | +- `references/first-pass-checklist.md` for choosing the first intent and entity surface |
| 15 | +- `references/example-patterns.md` for concrete example shapes to copy and adapt |
| 16 | +- `references/code-templates.md` for generalized App Intents code templates |
| 17 | +- `references/system-surfaces.md` for how to think about Shortcuts, Siri, Spotlight, widgets, and other system entry points |
| 18 | + |
| 19 | +## Core workflow |
| 20 | + |
| 21 | +### 1) Start with actions, not screens |
| 22 | + |
| 23 | +- Identify the 1-3 highest-value actions that should work outside the app UI. |
| 24 | +- Prefer verbs like compose, open, find, filter, continue, inspect, or start. |
| 25 | +- Do not mirror the entire app navigation tree as intents. |
| 26 | + |
| 27 | +### 2) Define a small entity surface |
| 28 | + |
| 29 | +- Add `AppEntity` types only for the objects the system needs to understand or route. |
| 30 | +- Keep the entity shape narrower than the app's persistence model. |
| 31 | +- Add `EntityQuery` or other query types only where disambiguation or suggestions are genuinely useful. |
| 32 | + |
| 33 | +### 3) Decide whether the action completes in place or opens the app |
| 34 | + |
| 35 | +- Use non-opening intents for actions that can complete directly from the system surface. |
| 36 | +- Use `openAppWhenRun` or open-style intents when the user should land in a specific in-app workflow. |
| 37 | +- When the app must react inside the main scene, add one clear runtime handoff path instead of scattering ad hoc routing logic. |
| 38 | +- If the action can work in both modes, consider shipping both an inline version and an open-app version rather than forcing one compromise. |
| 39 | + |
| 40 | +### 4) Make the actions discoverable |
| 41 | + |
| 42 | +- Add `AppShortcutsProvider` entries for the first set of high-value intents. |
| 43 | +- Choose titles, phrases, and symbols that make sense in Shortcuts, Siri, and Spotlight. |
| 44 | +- Keep shortcut phrases direct and task-oriented. |
| 45 | +- Reuse the same action model for widgets and controls when a widget configuration or intent-driven control already needs the same parameters. |
| 46 | + |
| 47 | +### 5) Validate the runtime handoff |
| 48 | + |
| 49 | +- Build the app and confirm the intents target compiles cleanly. |
| 50 | +- Verify the app opens or routes to the expected place when an intent runs. |
| 51 | +- Summarize which actions are now exposed, which entities back them, and how the app handles invocation. |
| 52 | + |
| 53 | +## Strong defaults |
| 54 | + |
| 55 | +- Prefer a dedicated intents target or module for the system-facing layer. |
| 56 | +- Keep intent types thin; business logic should stay in app services or domain models. |
| 57 | +- Keep app entities small and display-friendly. |
| 58 | +- Use `AppEnum` for fixed app choices such as tabs, modes, or visibility levels before reaching for a full entity type. |
| 59 | +- Prefer one predictable app-intent routing surface in the main app scene or root router. |
| 60 | +- Treat App Intents as system integration infrastructure, not only as a Shortcuts feature. |
| 61 | + |
| 62 | +## Anti-patterns |
| 63 | + |
| 64 | +- Exposing every screen or tab as its own intent without a real user value. |
| 65 | +- Mirroring the entire model graph as `AppEntity` types. |
| 66 | +- Hiding runtime handoff in global side effects with no clear app entry path. |
| 67 | +- Adding App Shortcuts with vague phrases or generic titles. |
| 68 | +- Treating the first App Intents pass as a broad taxonomy project instead of a small useful release. |
| 69 | + |
| 70 | +## Notes |
| 71 | + |
| 72 | +- Apple documentation to use as primary references: |
| 73 | + - `https://developer.apple.com/documentation/appintents/making-actions-and-content-discoverable-and-widely-available` |
| 74 | + - `https://developer.apple.com/documentation/appintents/creating-your-first-app-intent` |
| 75 | + - `https://developer.apple.com/documentation/appintents/adopting-app-intents-to-support-system-experiences` |
| 76 | +- In addition to the links above, use web search to consult current Apple Developer documentation when App Intents APIs or platform behavior may have changed. |
| 77 | +- A good first pass often includes one open-app intent, one action intent, one or two entity types, and a small `AppShortcutsProvider`. |
| 78 | +- Good example families to cover are: |
| 79 | + - open a destination or editor in the app |
| 80 | + - perform a lightweight action inline without opening the app |
| 81 | + - choose from a fixed enum such as a tab or mode |
| 82 | + - resolve one or more entities through `EntityQuery` |
| 83 | + - power widget configuration or controls from the same entity surface |
0 commit comments