Mobile Navigation

Mobile Navigation

Purpose

Plan the app's navigation: pick Expo Router or React Navigation, structure navigators, define typed route params, and expose the deep-link surface — consistent with the chosen runtime.

When to Use

• When designing the app's screen graph or adding a navigation area.
• When navigation state is duplicated into stores or params are untyped.
• Not for one-off in-screen state (that's local state).

Inputs

• Approved runtime (Expo/CLI) and screen list.
• Auth model (for protected routes) and deep-link needs.

Discovery Questions

• Expo Router (file-based) or React Navigation (config-based) — which fits the runtime/team?
• What navigator types are needed (stack/tab/drawer/modal)?
• Which routes are protected vs public?
• What deep links/universal links must resolve?

Responsibilities

• Choose Expo Router or React Navigation with justification.
• Define the navigator tree (stacks/tabs/drawers/modals).
• Define typed route params and the protected-route strategy (mobile-authorization).
• Coordinate deep linking (mobile-deep-linking) and safe-area handling.
• Keep navigation state owned by the navigator (mobile-state-management).
• Document the unit as it is built — docs/mobile/navigation.md, and one file per screen under docs/mobile/screens/ (../../application-documentation).

Required Workflow

1. Confirm runtime + screen list.
2. Pick router; justify.
3. Design navigator tree + typed params.
4. Mark protected routes; wire deep-link surface.
5. Record the navigation plan.

Decision Rules

• Expo Router suits Expo file-based apps; React Navigation suits config-based or CLI apps — choose by fit, not habit.
• Protected routes gate on auth server/session state, not hidden UI.
• Route params are typed; large objects are not passed through params.
• Navigation state lives in the navigator, not a global store.

Rules

• Match the approved runtime.
• Type route params; avoid passing large payloads.
• Defer auth checks to mobile-authorization and deep links to mobile-deep-linking.

Anti-Patterns

• Duplicating navigation state into Redux/Zustand.
• Passing large objects through route params.
• Guarding routes only by hiding UI.
• Mixing two navigation libraries without cause.

Validation Checklist

• Router chosen + justified.
• Navigator tree defined.
• Route params typed.
• Protected routes identified.
• Deep-link surface coordinated.
• Navigation state owned by navigator.

Definition of Done

A recorded navigation plan: chosen router, navigator tree, typed params, protected-route strategy, and deep-link surface — consistent with the runtime and with navigation state owned by the navigator.

Related Skills

mobile-deep-linking, mobile-authorization, mobile-authentication, mobile-state-management, expo-foundation, react-native-cli-foundation, ../../application-documentation.

Related Knowledge

../../../knowledge/ (screen graph, auth model).

Related References

../../../references/mobile/navigation/, ../../../references/mobile/screens/ when populated.

Context Loading Guidance

• Requires: approved runtime, screen list, auth + deep-link needs.
• Does not require: the whole app source, unrelated references, every mobile skill.
• May load: mobile-deep-linking, mobile-authorization for their surfaces.
• Stop when: the navigation plan is recorded.

Token Efficiency Guidance

Plan from the screen list and auth model; delegate deep-link/authorization detail to their skills instead of restating it.