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

arch-

anti-

| 3 | Transition & Animation | HIGH |

anim-

modal-

flow-

perf-

ally-

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