Navigation Patterns

Comprehensive guide for SwiftUI navigation architecture on iOS, iPadOS, and macOS. Covers the modern navigation APIs (iOS 16+/macOS 13+) with patterns for common and advanced use cases.

When This Skill Activates

• User is building or reviewing navigation architecture
• User has navigation-related bugs (stack not updating, back button issues, state loss)
• User asks about NavigationStack, NavigationSplitView, TabView, or NavigationPath
• User needs programmatic navigation (push, pop, pop-to-root)
• User is implementing deep linking that connects to navigation
• User asks about navigation transitions or animations
• User is choosing between navigation approaches for their app

Decision Tree

Use this to pick the right navigation container:

What is the app structure?
│
├─ Flat sections (3-5 top-level areas)
│  └─ TabView → see tab-view.md
│
├─ Hierarchical drill-down (list → detail)
│  └─ NavigationStack → see navigation-stack.md
│
├─ Sidebar + content (macOS / iPad)
│  ├─ Two columns → NavigationSplitView → see navigation-split-view.md
│  └─ Three columns → NavigationSplitView → see navigation-split-view.md
│
└─ Combined (tabs with drill-down, sidebar with stacks)
   └─ TabView + NavigationStack per tab
      OR NavigationSplitView + NavigationStack in detail

Quick Reference

Process

1. Identify Navigation Needs

Read the user's code or requirements to determine:

• App structure (flat, hierarchical, sidebar-based)
• Target platforms (iOS only, iPad adaptive, macOS)
• Whether programmatic navigation is needed
• Deep linking requirements

2. Load Relevant Reference Files

Based on the need, read from this directory:

• navigation-stack.md — NavigationStack, NavigationLink, navigationDestination
• navigation-split-view.md — Two/three column layouts, column control, adaptive behavior
• tab-view.md — TabView, iOS 18 customizable tabs, sidebar mode
• programmatic-navigation.md — NavigationPath, state restoration, coordinators, pop-to-root
• navigation-transitions.md — Custom push/pop transitions (iOS 18+)

3. Review or Recommend

Apply patterns from the reference files. Check for common mistakes:

• Using deprecated NavigationView instead of NavigationStack/NavigationSplitView
• Using NavigationLink(destination:) instead of NavigationLink(value:) + .navigationDestination
• Placing NavigationStack inside NavigationSplitView detail (usually wrong)
• Missing .navigationDestination registration for a value type
• NavigationPath not @State or not in the right scope
• Multiple NavigationStacks competing for the same navigation context
• Hard-coding navigation instead of using NavigationPath for programmatic control
• Not handling deep links through the navigation system

4. Cross-Reference

• For deep linking URL handling, see generators/deep-linking/ skill
• For navigation animations, see design/animation-patterns/transitions.md
• For macOS sidebar patterns, see macos/ui-review-tahoe/swiftui-macos.md

References

• NavigationStack
• NavigationSplitView
• NavigationPath
• TabView
• Migrating to new navigation types