Agent-Skills.md

Agent Skills: Navigation Patterns

SwiftUI navigation architecture patterns including NavigationStack, NavigationSplitView, TabView, programmatic navigation, and custom transitions. Use when reviewing or building navigation, fixing navigation bugs, or architecting app flow.

UncategorizedID: rshankras/claude-code-apple-skills/navigation-patterns

Repository

rshankras/claude-code-apple-skills
rshankrasLicense: MIT
11710

Install this agent skill to your local

pnpm dlx add-skill https://github.com/rshankras/claude-code-apple-skills/tree/HEAD/skills/ios/navigation-patterns

Skill Files

Browse the full folder contents for navigation-patterns.

Download Skill

Loading file tree…

skills/ios/navigation-patterns/SKILL.md

Skill Metadata

Name
navigation-patterns
Description
SwiftUI navigation architecture patterns including NavigationStack, NavigationSplitView, TabView, programmatic navigation, and custom transitions. Use when reviewing or building navigation, fixing navigation bugs, or architecting app flow.

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

| Pattern | Container | Min OS | Reference | |---------|-----------|--------|-----------| | Simple drill-down | NavigationStack | iOS 16 | navigation-stack.md | | Value-based links | NavigationLink(value:) | iOS 16 | navigation-stack.md | | Programmatic push/pop | NavigationPath | iOS 16 | programmatic-navigation.md | | Pop to root | path = NavigationPath() | iOS 16 | programmatic-navigation.md | | State restoration | NavigationPath.CodableRepresentation | iOS 16 | programmatic-navigation.md | | Two-column layout | NavigationSplitView | iOS 16 | navigation-split-view.md | | Three-column layout | NavigationSplitView | iOS 16 | navigation-split-view.md | | Column visibility | NavigationSplitViewVisibility | iOS 16 | navigation-split-view.md | | Tab bar | TabView | iOS 13 | tab-view.md | | Customizable tabs | Tab + TabView | iOS 18 | tab-view.md | | Sidebar tabs (iPad) | .tabViewStyle(.sidebarAdaptable) | iOS 18 | tab-view.md | | Zoom transition | .navigationTransition(.zoom) | iOS 18 | navigation-transitions.md | | Custom transitions | NavigationTransition | iOS 18 | navigation-transitions.md |

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