Implement mobile navigation

Mobile Screens & Navigation

Turn the UI/UX designer's screen plans and interactions into predictable mobile flows that respect iOS and Android navigation habits, safe areas, software keyboards and screen sizes.

1. Navigation hierarchy, route params and back behavior

• Typed, serializable route parameters: pass only compact identifiers and filter primitives (id, slug, tab)—never pass class instances, closures or large objects in navigation params, as they break deep links, URL restoration and OS state restoration (SavedStateHandle / RestorationMixin).
• Auth and onboarding gates: use declarative guards (<Stack.Protected guard={!!session}> in Expo Router, redirect + refreshListenable in go_router, or conditional root stacks) so sign-out or session expiry clears protected screens from the back stack without flashing private content.
• Hardware & gesture back handling:
  • Support iOS swipe-back and Android 14+ predictive back gestures (PopScope<T> with canPop and onPopInvokedWithResult in Flutter; BackHandler / beforeRemove in React Navigation; BackHandler in Compose).
  • Dismiss open bottom sheets, dialogs or selection modes before popping the screen, and prompt or auto-save drafts before discarding unsaved form input.
  • After login, onboarding or checkout, replace (router.replace / context.go) rather than push so Back never returns to the completed step.

2. Safe areas, edge-to-edge layout and virtual keyboard

• Safe areas & cutouts: use react-native-safe-area-context (useSafeAreaInsets, SafeAreaView), Flutter SafeArea / MediaQuery.paddingOf(context), or Compose WindowInsets.safeDrawing so notches, Dynamic Island, status bars and gesture bars never clip interactive controls, while backgrounds and scrolling lists bleed cleanly to the screen edge.
• Keyboard avoidance & focus flow:
  • Keep focused inputs and the primary submit button visible above the software keyboard (KeyboardAvoidingView with platform behavior / react-native-keyboard-controller, Flutter Scaffold(resizeToAvoidBottomInset: true) + SingleChildScrollView, Compose imePadding()).
  • Set appropriate keyboardType / textInputAction (next, done, search, send), chain focus between fields, and configure keyboardShouldPersistTaps="handled" on scroll views so tapping a submit button while the keyboard is open works on the first tap.
• Responsive & adaptive layout: test narrow phones (320 pt), large phones, tablets/foldables (useWindowDimensions, LayoutBuilder) and system font scaling up to 200%.

3. Four mandatory states per data screen

1. Loading: layout-stable skeleton or spinner plus pull-to-refresh (RefreshControl / RefreshIndicator).
2. Empty: clear explanation and primary CTA when a list or search returns zero items.
3. Error: clear reason (offline vs server error) with an inline Retry button that preserves filters/input.
4. Populated: smooth content with touch targets >= 44x44 pt (iOS) / 48x48 dp (Android).

Before you finish

• Route params are typed IDs/primitives; auth gates and post-submit stack resets prevent dead ends.
• iOS swipe-back and Android predictive back / hardware back respect modals and unsaved drafts.
• Safe areas, keyboard avoidance (imePadding / KeyboardAvoidingView) and tap-through while keyboard is open work.
• Loading, empty, error (with retry) and populated states are all implemented.