navigation-patterns_skill

Overview

This skill advises on choosing and implementing navigation patterns for iOS and tvOS apps, focusing on NavigationStack vs Coordinator, NavigationPath trade-offs, deep link handling, and tab + navigation coordination. It delivers practical rules, decision trees, and code-guided guidance to design predictable, testable navigation. Use it when designing app navigation architecture, implementing deep links, or debugging navigation-state issues.

How this skill works

The skill inspects your app's navigation complexity and recommends patterns: inline NavigationLink for simple linear flows, a typed Router with a typed array for medium complexity, and a tab-coordinator with per-tab routers for complex multi-stack apps. It evaluates whether you need type-erased NavigationPath or type-safe route enums, how to queue and handle deep links across cold and warm starts, and when to present modals vs push navigation. It also highlights anti-patterns and provides safe defaults for state ownership and persistence.

When to use it

• Designing high-level navigation architecture for a new SwiftUI app
• Deciding between NavigationPath and a type-safe route enum
• Implementing or debugging deep link routing across cold/warm starts
• Coordinating tabs that require independent navigation stacks
• Refactoring navigation-coupled view models into router/coordinator patterns

Best practices

• Prefer type-safe route enums and typed arrays unless you truly need heterogeneous route types
• Keep NavigationPath or navigation state inside a Router/Coordinator, not business ViewModels
• Give each tab its own Router and NavigationPath to avoid cross-tab state leaks
• Queue deep links received before the view hierarchy exists and handle them onAppear
• Persist critical navigation state only when UX demands restoring user context

Example use cases

• A single-flow utility app: use NavigationStack with inline NavigationLink, no router
• An app with deep linking and multiple flows: Router with @Published typed path and centralized handler
• A tabbed app with cross-tab navigation: Tab coordinator with per-tab routers and popToRoot on re-selection
• Handling universal links: parse URL into DeepLink enum, queue on cold start, then router.handle(deepLink)
• Migrating a ViewModel that owns NavigationPath: extract navigation into a Router and keep ViewModel data-only