SwiftUI navigation and presentation
Read references/navigation-and-presentation.md whenever routes, selection, tabs, sheets, popovers, alerts, dialogs, windows, or deep links change.
Workflow
- Define the information hierarchy plus restoration and deep-link requirements.
- Choose
NavigationSplitView for persistent selection/detail relationships and NavigationStack for a bounded hierarchy.
- Model destinations as stable
Hashable values and keep navigation state with the workflow owner.
- Register each destination type once in a hierarchy.
- Verify narrow-window behaviour, split-view collapse, selection preservation, empty-detail handling, and back behaviour in stack flows.
- Use item-driven presentation when a modal represents optional data.
- Attach confirmation dialogs and popovers to the triggering control.
- Test invalid or stale destinations, deep links, and restoration where applicable.
- Review keyboard commands, focus, pointer, VoiceOver, Voice Control, and multi-window behaviour.
Guardrails
- Do not use
NavigationView for new code.
- Do not mix value-driven and destination-closure navigation in one hierarchy without a documented interoperability reason.
- Register each
navigationDestination(for:) type once per hierarchy.
- Show a useful unavailable state when detail selection is absent.
- Use
sheet(item:) when optional data owns modal presentation.
- Avoid a global router unless independent scenes need coordinated routes.
Output
Describe route values, path or selection ownership, presentation state, narrow-window behaviour, restoration, and the manual macOS checks performed. Report failures with their window and input context.
1---2name: swiftui-navigation3description: Design or review typed macOS SwiftUI navigation, split views, tabs, deep links, selection, sheets, popovers, alerts, dialogs, and windows.4license: MIT5---67# SwiftUI navigation and presentation89Read `references/navigation-and-presentation.md` whenever routes, selection, tabs, sheets, popovers, alerts, dialogs, windows, or deep links change.1011## Workflow12131. Define the information hierarchy plus restoration and deep-link requirements.142. Choose `NavigationSplitView` for persistent selection/detail relationships and `NavigationStack` for a bounded hierarchy.153. Model destinations as stable `Hashable` values and keep navigation state with the workflow owner.164. Register each destination type once in a hierarchy.175. Verify narrow-window behaviour, split-view collapse, selection preservation, empty-detail handling, and back behaviour in stack flows.186. Use item-driven presentation when a modal represents optional data.197. Attach confirmation dialogs and popovers to the triggering control.208. Test invalid or stale destinations, deep links, and restoration where applicable.219. Review keyboard commands, focus, pointer, VoiceOver, Voice Control, and multi-window behaviour.2223## Guardrails2425- Do not use `NavigationView` for new code.26- Do not mix value-driven and destination-closure navigation in one hierarchy without a documented interoperability reason.27- Register each `navigationDestination(for:)` type once per hierarchy.28- Show a useful unavailable state when detail selection is absent.29- Use `sheet(item:)` when optional data owns modal presentation.30- Avoid a global router unless independent scenes need coordinated routes.3132## Output3334Describe route values, path or selection ownership, presentation state, narrow-window behaviour, restoration, and the manual macOS checks performed. Report failures with their window and input context.
rcarmo