Mobile Navigation Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Navigation documentation index: NAVIGATION_GUIDE_INDEX.md

Major changes vs v1.4.0:

• Removes references to MobileMenuSheet (consolidated into MobileNavMore per ResponsiveNav.tsx 2026-Q1).
• Updates the component map to reflect the current MobileNav (4-slot dock + More drawer), MobileNavMore, MobileNavDockSheetContent, MobileSidebarNav (feature-flagged).
• Adds the new BottomTabBar shared primitive for core-level bottom navs (CE today; HR/RH later).
• Aligns CSS-var examples with production (--mobile-nav-height: 76px, --mobile-header-height: 48px, --mobile-header-context-height: 32px).
• Codifies the mobile-component-location convention (cores//components/mobile/).
• Edge-swipe back is now bound to the main scroll area (PR-3.2 in the mobile-gestures consistency plan), not just the header.

​

Overview

• Bottom tab bar for primary navigation (< 768 px).
• Top header with logo, search, notifications, and a contextual primary action.
• Mobile breadcrumbs (last 2 segments) for hierarchical context.
• More drawer (MobileNavMore + MobileNavDockSheetContent) for secondary navigation, themes, sign-out, and module switching.
• Desktop: Sidebar (SidebarProvider + AppSidebar + SidebarInset) at ≥ 768 px. Other nav modes (Dock, Taskbar) live in NavModeContext.

​

Quick Reference

​

Component map (current)

MobileMenuSheet was removed in 2026-Q1 — its responsibilities are now in MobileNavMore + MobileNavDockSheetContent.

​

Context-aware bottom navigation (2026-Q2)

1. Platform mode (default): Shows the user’s 3 customizable shortcut slots + More. Active when no module is detected.
2. Module mode: When the user is inside a module (detected via useModuleRouting), the bottom bar automatically transforms to show that module’s top navigation sections (derived from MODULE_REGISTRY.navGroups via useModuleBottomTabs), plus the More button.

​

Common patterns

// Platform mobile nav (auto-rendered by ResponsiveNav; do not embed manually)
<ResponsiveNav user={user}>
  <Routes />
</ResponsiveNav>

// Module bottom tabs are now auto-generated from MODULE_REGISTRY:
// - useModuleBottomTabs(currentModule) derives up to 3 tabs from navGroups
// - MobileNav renders them when isModuleRoute is true
// No manual BottomTabBar usage needed for new modules.

// CE legacy bottom nav (still used for QuickLogFAB/offline; will be migrated)
<BottomTabBar
  ariaLabel="CE mobile navigation"
  tabs={CE_MOBILE_TABS}
/>

​

Key requirements

• Touch targets: ≥ 44 × 44 px (WCAG 2.1 AAA, Apple HIG). Use min-w-[44px] min-h-[44px].
• Safe areas: all fixed surfaces apply env(safe-area-inset-*) via the CSS vars below.
• Breakpoints: mobile < 768 px, desktop ≥ 768 px. Use useIsMobile() from @/shared/lib/hooks/use-mobile (do not use useMediaQuery for the mobile breakpoint).
• Z-index: bottom nav uses z-50; app-lock overlay (PF-79) wins at z-[100].
• Content padding: the <main> inside ResponsiveNav already pads top + bottom for header/nav heights using CSS vars.

​

Common issues

​

CSS Variables (Single Source of Truth)

:root {
  --safe-area-inset-top: env(safe-area-inset-top, 0px);
  --safe-area-inset-bottom: env(safe-area-inset-bottom, 0px);
  --safe-area-inset-left: env(safe-area-inset-left, 0px);
  --safe-area-inset-right: env(safe-area-inset-right, 0px);
  --mobile-header-height: 48px;
  --mobile-header-context-height: 32px;
  --mobile-nav-height: 76px;
  --dock-height: 72px;
}

• .safe-area-top / .safe-area-bottom / .safe-area-left / .safe-area-right
• .no-pull-refresh (overscroll-behavior-y: contain)
• .scrollbar-thin / .scrollbar-x / .scrollbar-y for scroll-area styling

​

1. Architecture

ResponsiveNav (handles mobile/desktop switching via useIsMobile)
├── Mobile (< 768px)
│   ├── MobileHeader (top app bar)
│   ├── <main> with pt/pb computed from CSS vars
│   ├── MobileNav (bottom dock — 4 slots + More)
│   │   └── MobileNavMore → MobileNavDockSheetContent
│   ├── ContextualActionFAB (above bottom nav)
│   └── (optional) MobileSidebarNav (feature flag pf.mobile_sidebar_nav)
└── Desktop (>= 768px)
    └── SidebarProvider + AppSidebar + SidebarInset

​

2. Bottom Navigation

​

Platform MobileNav

[shortcut 1] [shortcut 2] [shortcut 3] [shortcut 4] [More]

• A sliding pill underline animates between the active item.
• aria-current="page" is set on the active link.

​

Core-level BottomTabBar (new)

import { BottomTabBar } from '@/platform/navigation/components/BottomTabBar';

<BottomTabBar
  ariaLabel="CE mobile navigation"
  tabs={[
    { key: 'dashboard', label: 'Dashboard', icon: BarChart3, path: '/ce', permission: 'ce.dashboard.view' },
    { key: 'contacts',  label: 'Contacts',  icon: Users,     path: '/ce/contacts', permission: 'ce.contacts.view' },
    { key: 'partners',  label: 'Partners',  icon: Building2, path: '/ce/partners', permission: 'ce.partners.view' },
    { key: 'activities', label: 'Activities', icon: Phone,    path: '/ce/activities', permission: 'ce.activities.view' },
  ]}
/>

​

Stacking with the platform nav

• Either offset the core nav above the platform nav (default), or
• Hide the platform nav for the route by checking useNavigation().isSubModuleRoute and conditionally rendering. (Decision: keep both for now; CE has confirmed the dual-nav UX.)

​

3. More Drawer (MobileNavMore + MobileNavDockSheetContent)

1. User profile header with avatar.
2. Notifications inbox link.
3. AI Assistant launch.
4. Theme toggle.
5. Phone / Log Call (RingCentral integration).
6. All modules grid (collapsible by category).
7. Search.
8. Sign out.

​

4. Safe Area Insets

<nav style={{ paddingBottom: 'var(--safe-area-inset-bottom, 0px)' }}>

<nav className="safe-area-bottom">

​

Test devices

• iPhone X / XS / 11 / 12 / 13 / 14 / 15 (notched + home indicator)
• iPhone 14 / 15 Pro (Dynamic Island)
• Pixel 6 / 7 / 8 (home indicator)
• iPad Pro / iPad Air

​

5. Touch Targets

<Button className="min-h-[44px] min-w-[44px]" aria-label="Open menu">
  <Menu className="size-5" aria-hidden="true" />
</Button>

​

6. Mobile-Component Location Convention (new)

• CE: dedicated src/cores/ce/components/mobile/ folder.
• CL / HR: Mobile<Name>.tsx colocated with desktop peer.
• FM / LO / RH: nothing (all responsive in one file).

1. Mobile-only components that don’t have a 1:1 desktop sibling → put under src/cores/{core}/components/mobile/.
2. Mobile variants of existing components (small) → colocate as <Name>.mobile.tsx peer to <Name>.tsx.

• Mobile<Domain><Surface> (e.g. MobileVitalsKeypad, MobileBottomNav).
• Use Sheet not Drawer / Modal in new file names (per root AGENTS.md). Existing names with Drawer are grandfathered until renamed (see MobileVitalsDrawer → MobileVitalsSheet rename in PR-2.5).

​

7. Edge Swipe Back Navigation (updated)

// ResponsiveNav.tsx (mobile branch)
const edgeSwipe = useEdgeSwipe({
  onBack: () => navigate(-1),
  enabled: routeDepth >= 2,
  edgeWidth: 20,    // 20 px from left edge
  threshold: 100,   // 100 px swipe to commit
});

​

8. Offline Navigation

import { useOnlineStatus } from '@/shared/hooks/useOnlineStatus';
const isOnline = useOnlineStatus();

​

9. Navigation Error Boundaries

​

10. Testing Checklist

​

Functional

• Bottom nav appears on mobile (< 768 px), hidden on desktop.
• More drawer opens/closes.
• Edge swipe back navigates one level (route depth ≥ 2).
• Customize dialog (long-press More) saves preferences.
• Core-level BottomTabBar filters by permission.

​

Safe areas

• iPhone X+ / Pro models — no overlap with notch / Dynamic Island.
• Pixel 7+ — bottom nav above home indicator.
• Landscape orientation — left/right insets honored.

​

Touch targets

• All bottom-nav buttons ≥ 44 × 44 px.
• Header icon buttons ≥ 44 × 44 px.
• Drawer rows ≥ 44 px tall.

​

Accessibility

• aria-current="page" on active tab.
• aria-label on every icon-only button.
• Esc closes the More drawer.
• Skip-to-content link works from keyboard.
• Keyboard arrow keys navigate between bottom-nav slots (MobileNav already implements this).

​

Hydration / first paint

• No desktop chrome flash on real mobile devices (PR-3.1 fix in useIsMobile).
• Boot splash transitions cleanly.

​

Cross-browser

• iOS Safari 14+ ✅
• Android Chrome 90+ ✅
• Firefox / Edge mobile

​

11. Mobile Breadcrumbs

useEntityBreadcrumb(patient, (p) => `${p.last_name}, ${p.first_name}`);

​

12. Best Practices Summary

1. Use CSS vars (--mobile-nav-height, --safe-area-inset-*) for all fixed-element spacing; never hard-code.
2. Keep touch targets at 44 × 44 px minimum.
3. Use useIsMobile for the 768-px breakpoint; useMediaQuery is reserved for non-standard breakpoints and is @deprecated for the mobile case.
4. Place mobile-only components under src/cores/{core}/components/mobile/.
5. Use the Sheet primitive for slide-up panels (not “Drawer” or “Modal” in new code).
6. Use BottomTabBar for core-level mobile navs (CE today; HR/RH if needed).
7. Use SwipeableCardShell (from @/platform/gestures) instead of hand-rolled *Swipeable.tsx wrappers.
8. Set aria-current="page" on active tabs and aria-label on icon-only buttons.
9. Honor prefers-reduced-motion automatically — Phase 1 gesture hooks already do this (PR-3.3).
10. Test on real notched iOS + home-indicator Android devices (or Chrome DevTools device emulation).

​

13. Quick Actions Pattern (PF-20)

​

14. Mobile Swipe Gestures

​

15. References

• Constitution §6 — PWA & UI requirements
• Spec: PF-13 PWA & Mobile Navigation Improvements
• Spec: PF-37 Mobile Swipe Gestures
• Spec: PF-79 Mobile App Security (biometric / PIN / session lock)
• Plan: PF Mobile Touch & Scroll Improvement Plan
• Guide: Mobile Gesture Guide v2.0.0
• Guide: Breadcrumb Implementation Guide
• Component: ResponsiveNav.tsx
• Component: MobileNav.tsx
• Component: BottomTabBar.tsx (new)
• Hook: useIsMobile
• WCAG 2.1 Target Size
• Apple HIG Layout — Touch targets