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

| 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