ios-navigation

iOS Navigation (Modular MVVM-C)

Opinionated navigation enforcement for SwiftUI apps using the clinic modular architecture. Focus on coordinator + route shell wiring, feature isolation, and resilient push/sheet/deep-link flows.

Non-Negotiable Constraints (iOS 26 / Swift 6.2)

• @Equatable macro on every navigation view, AnyView never
• @Observable everywhere, ObservableObject / @Published never
• App-target coordinators own NavigationPath; route shells own .navigationDestination mappings
• Coordinator-owned modal state, inline @State booleans for sheets never
• Domain layer defines coordinator protocols; concrete coordinators stay out of feature modules

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

• Feature modules import Domain + DesignSystem only (never Data, never sibling features)
• App target is the convergence point and owns DependencyContainer, concrete coordinators, and Route Shell wiring
• Domain stays pure Swift and defines models plus repository, *Coordinating, ErrorRouting, and AppError contracts
• Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
• Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
• ViewModels call repository protocols directly (no default use-case/interactor layer)

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 and modular architecture compliance
• Adding deep linking, state restoration, or tab persistence
• Ensuring VoiceOver and reduce motion support for navigation

Rule Categories by Priority

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 26 / Swift 6.2)
• 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
• arch-equatable-views - Apply @Equatable macro to every navigation view
• arch-observable-only - Use @Observable only — never ObservableObject or @Published
• arch-no-anyview - Never use AnyView in navigation — use @ViewBuilder or generics
• arch-coordinator-modals - Present all modals via coordinator — never inline @State

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 26 / Swift 6.2)
• 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

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