ios-navigation

Original：🇺🇸 English

Translated

SwiftUI NavigationStack, NavigationSplitView, and navigation transition patterns for iOS 16-18+. Covers @Observable coordinators, zoom transitions, hero animations, sheet vs push decisions, multi-step flows, anti-patterns, performance, accessibility, deep linking, and state restoration. This skill should be used when designing navigation hierarchies, implementing screen transitions, choosing between sheet and push, orchestrating multi-step flows, using @Observable with @Environment and @Bindable, or reviewing navigation code for anti-patterns.

1installs

Sourcepproenca/dot-skills

Added on2026-02-16

NPX Install

npx skill4agent add pproenca/dot-skills ios-navigation

SKILL.md Content

View Translation Comparison →

Apple iOS Navigation Best Practices

Comprehensive guide for building fluid, golden-standard navigation in iOS apps with SwiftUI. Contains 51 rules across 8 categories covering architecture, anti-patterns, transitions, modals, flow orchestration, performance, accessibility, and state restoration.

When to Apply

Reference these guidelines when:

Designing navigation hierarchies with NavigationStack or NavigationSplitView
Choosing between push, sheet, and fullScreenCover
Implementing hero animations, zoom transitions, or gesture-driven dismissals
Building multi-step flows (onboarding, checkout, registration)
Using @Observable with @Environment and @Bindable for shared navigation state
Reviewing code for navigation anti-patterns
Adding deep linking, state restoration, or tab persistence
Ensuring VoiceOver and reduce motion support for navigation

Rule Categories by Priority


arch-
anti-
anim-
modal-
flow-
perf-
ally-
state-

Priority	Category	Impact	Prefix
1	Navigation Architecture	CRITICAL	`arch-`
2	Navigation Anti-Patterns	CRITICAL	`anti-`
3	Transition & Animation	HIGH	`anim-`
4	Modal Presentation	HIGH	`modal-`
5	Flow Orchestration	HIGH	`flow-`
6	Navigation Performance	MEDIUM-HIGH	`perf-`
7	Navigation Accessibility	MEDIUM	`ally-`
8	State & Restoration	MEDIUM	`state-`

Quick Reference

1. Navigation Architecture (CRITICAL)

```
arch-navigation-stack
```
- Use NavigationStack over deprecated NavigationView
```
arch-value-based-links
```
- Use value-based NavigationLink over destination closures
```
arch-destination-registration
```
- Register navigationDestination at stack root
```
arch-destination-item
```
- Use navigationDestination(item:) for optional-based navigation (iOS 17+)
```
arch-route-enum
```
- Define routes as Hashable enums
```
arch-split-view
```
- Use NavigationSplitView for multi-column layouts
```
arch-coordinator
```
- Extract navigation logic into Observable coordinator
```
arch-observable-environment
```
- Use @Environment with @Observable and @Bindable for shared state
```
arch-deep-linking
```
- Handle deep links by appending to NavigationPath
```
arch-navigation-path
```
- Use NavigationPath for heterogeneous type-erased navigation

2. Navigation Anti-Patterns (CRITICAL)

```
anti-mixed-link-styles
```
- Avoid mixing NavigationLink(destination:) with NavigationLink(value:)
```
anti-scattered-destinations
```
- Avoid scattering navigationDestination across views
```
anti-shared-stack
```
- Avoid sharing NavigationStack across tabs
```
anti-hidden-back-button
```
- Avoid hiding back button without preserving swipe gesture
```
anti-navigation-in-init
```
- Avoid heavy work in view initializers
```
anti-hamburger-menu
```
- Avoid hamburger menu navigation
```
anti-programmatic-tab-switch
```
- Avoid programmatic tab selection changes

3. Transition & Animation (HIGH)

```
anim-zoom-transition
```
- Use zoom navigation transition for hero animations (iOS 18+)
```
anim-matched-geometry-same-view
```
- Use matchedGeometryEffect only within same view hierarchy
```
anim-spring-config
```
- Use modern spring animation syntax (iOS 17+)
```
anim-gesture-driven
```
- Use interactive spring animations for gesture-driven transitions
```
anim-transition-source-styling
```
- Style transition sources with shape and background
```
anim-reduce-motion-transitions
```
- Respect reduce motion for all navigation animations
```
anim-scroll-driven
```
- Use onScrollGeometryChange for scroll-driven transitions (iOS 18+)

4. Modal Presentation (HIGH)

```
modal-sheet-vs-push
```
- Use push for drill-down, sheet for supplementary content
```
modal-detents
```
- Use presentation detents for contextual sheet sizing
```
modal-fullscreen-cover
```
- Use fullScreenCover only for immersive standalone experiences
```
modal-sheet-placement
```
- Place .sheet on container view, not on NavigationLink
```
modal-interactive-dismiss
```
- Guard unsaved changes with interactiveDismissDisabled
```
modal-nested-navigation
```
- Use separate NavigationStack inside modals

5. Flow Orchestration (HIGH)

```
flow-tab-independence
```
- Give each tab its own NavigationStack
```
flow-multi-step
```
- Use NavigationStack with route array for multi-step flows
```
flow-sidebar-navigation
```
- Use NavigationSplitView with selection binding for sidebar
```
flow-tab-sidebar-adaptive
```
- Use sidebarAdaptable TabView for iPad tab-to-sidebar (iOS 18+)
```
flow-pop-to-root
```
- Implement pop-to-root by clearing NavigationPath
```
flow-screen-independence
```
- Keep screens independent of parent navigation context

6. Navigation Performance (MEDIUM-HIGH)

```
perf-lazy-destinations
```
- Use value-based NavigationLink for lazy destination construction
```
perf-task-modifier
```
- Use .task for async data loading on navigation
```
perf-state-object-ownership
```
- Own @Observable state with @State, pass as plain property
```
perf-avoid-body-side-effects
```
- Avoid side effects in view body
```
perf-lazy-view-wrapper
```
- Use LazyView wrapper for pre-iOS 16 destination loading

7. Navigation Accessibility (MEDIUM)

```
ally-rotor-headers
```
- Mark navigation section headers for VoiceOver rotor
```
ally-focus-after-navigation
```
- Manage focus after programmatic navigation events
```
ally-group-navigation-elements
```
- Group related navigation elements to reduce swipe count
```
ally-hide-decorative-navigation
```
- Hide decorative navigation elements from VoiceOver
```
ally-keyboard-focus
```
- Use @FocusState for keyboard navigation in forms

8. State & Restoration (MEDIUM)

```
state-codable-routes
```
- Make route enums Codable for navigation persistence
```
state-scene-storage
```
- Use SceneStorage for per-scene navigation persistence
```
state-tab-persistence
```
- Persist selected tab with SceneStorage
```
state-deep-link-urls
```
- Parse deep link URLs into route enums
```
state-avoid-app-level-path
```
- Avoid defining NavigationPath at App level

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information