Encore OS — Documentation

Version: 2.0.0 Last Updated: 2026-04-19 Purpose: Detailed guide for implementing mobile navigation patterns in Encore OS

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

Encore OS uses a mobile-first navigation system:

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)

Component	Path	Purpose
`ResponsiveNav`	`src/platform/navigation/ResponsiveNav.tsx`	Top-level mobile/desktop switch
`MobileNav`	`src/platform/navigation/MobileNav.tsx`	4-slot bottom dock with More button
`MobileNavMore`	`src/platform/navigation/MobileNavMore.tsx`	Sheet trigger for the More drawer
`MobileNavDockSheetContent`	`src/platform/navigation/MobileNavDockSheetContent.tsx`	Drawer body (modules, settings, theme, sign-out)
`MobileHeader`	`src/platform/navigation/MobileHeader.tsx`	Top app bar (logo, back, search, notifications)
`MobileBreadcrumbs`	`src/platform/navigation/MobileBreadcrumbs.tsx`	Compact 2-segment crumb row
`MobileOrgSwitcher`	`src/platform/navigation/MobileOrgSwitcher.tsx`	Multi-org switcher in context row
`MobileSidebarNav`	`src/platform/navigation/MobileSidebarNav.tsx`	Feature-flagged (`pf.mobile_sidebar_nav`) full-tree drawer
`MobileModuleSwitcher`	`src/platform/modules/MobileModuleSwitcher.tsx`	Module grid inside the More drawer
`MobileModuleIcon`	`src/platform/modules/MobileModuleIcon.tsx`	Module icon helper
`BottomTabBar`	`src/platform/navigation/components/BottomTabBar.tsx`	Reusable mobile bottom-tab primitive (module-level navs)
`useModuleBottomTabs`	`src/platform/navigation/hooks/useModuleBottomTabs.ts`	Derives bottom-bar tabs from MODULE_REGISTRY navGroups
`MobileModuleNavStrip` (new)	`src/platform/navigation/components/MobileModuleNavStripImpl.tsx`	Scrollable chip bar for in-module section switching
`useRoleBasedDefaults` (new)	`src/platform/navigation/hooks/useRoleBasedDefaults.ts`	Role-based default shortcut presets
`useNavigationFrequency` (new)	`src/platform/navigation/hooks/useNavigationFrequency.ts`	Tracks module visit frequency for suggestions

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

MobileNav now operates in two modes:

Platform mode (default): Shows the user’s 3 customizable shortcut slots + More. Active when no module is detected.
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.

The More drawer is also context-aware: when opened from inside a module, it auto-navigates to that module’s L2 groups instead of the top-level modules grid (initialModuleId prop). Dead core-level MobileBottomNav files in CL, PM, and HR were removed in 2026-Q2. CE’s MobileBottomNav / MobileCrmShell remain for CE-specific features (QuickLogFAB, offline indicator) but the CE tab bar will be superseded by the platform context-aware pattern.

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

Symptom	Fix
Content hidden behind bottom nav	The mobile `<main>` already adds `pb-[calc(var(--mobile-nav-height,64px) + var(--safe-area-inset-bottom,0px))]`. If you bypass it, add the same padding.
Safe area not honored	Make sure the viewport meta tag has `viewport-fit=cover` (✅ in `index.html`).
Touch target too small	Add `min-w-[44px] min-h-[44px]` to the button.
Hydration flash on mobile	`useIsMobile` now reads `window.innerWidth` synchronously on mount (PR-3.1) — verify your code calls the hook from `@/shared/lib/hooks/use-mobile`.

CSS Variables (Single Source of Truth)

Defined in src/index.css:

: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;
}

Helper utility classes (also in index.css):

.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 (compact bottom dock — up to 4 slots + More; no center FAB)
│   │   └── MobileNavMore → MobileNavDockSheetContent (hosts per-screen quick actions)
│   └── (optional) MobileSidebarNav (feature flag pf.mobile_sidebar_nav)
└── Desktop (>= 768px)
    └── SidebarProvider + AppSidebar + SidebarInset

The useEdgeSwipe for back navigation is bound to the mobile main scroll container (PR-3.2), so it can fire from anywhere in the left 20 px of the viewport — not just the 48 px header.

Platform `MobileNav`

The platform-level bottom nav lives at src/platform/navigation/MobileNav.tsx and renders a compact single-row dock of up to 4 slots + a More button (no raised center FAB):

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

Shortcuts come from useMobileNavPreferences (per-user) filtered against permission via useMobileNavAllowedShortcuts. The list is configured in mobile-nav-config.ts. Long-pressing a slot (or “Edit Dock” in the More drawer) lets the user swap or reorder shortcuts. The raised center “morphing FAB” was removed. Per-screen quick actions (the contextual primary action + context actions) now live at the top of the More drawer. Users who want a quick-actions launcher on the bar can pin the Quick Actions shortcut (open-quick-actions) to a slot via the slot-swap sheet. Active-state visuals:

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

Core-level `BottomTabBar` (new)

For modules that need a module-scoped bottom nav (today only CE; potentially HR / RH for field staff), use the shared primitive at src/platform/navigation/components/BottomTabBar.tsx:

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

A core-level BottomTabBar does not replace the platform MobileNav — both can render. To avoid double-stacking:

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`)

Replaces the legacy MobileMenuSheet. Contents:

User profile header with avatar.
Notifications inbox link.
AI Assistant launch.
Theme toggle.
Phone / Log Call (RingCentral integration).
All modules grid (collapsible by category).
Search.
Sign out.

To customize the drawer, do not embed it manually — it’s instantiated inside MobileNav.

4. Safe Area Insets

Already wired into index.css. Consumers reference the CSS vars:

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

or with the helper class:

<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>

Spacing: gap-2 (8 px) minimum between adjacent targets.

6. Mobile-Component Location Convention (new)

Cores have grown three different conventions for “where do mobile-only components live?”:

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).

Going forward, use one of these two patterns (in order of preference):

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

Naming:

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).

This convention is also pinned in src/cores/AGENTS.md and per-core AGENTS files where mobile work is active.

The hook (useEdgeSwipe) is now bound to the main mobile scroll container in ResponsiveNav rather than only MobileHeader. This means a left-edge swipe anywhere in the visible viewport — not just the 48 px header — triggers back navigation.

// 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
});

Visual indicator (1 px primary-color bar) overlays the viewport when the gesture is active. If a page does not want edge-swipe back (e.g. a horizontally-scrollable canvas), wrap the page root in a div with style={{ touchAction: 'pan-x' }} to opt out.

Use the existing useOnlineStatus hook. The MobileHeader shows an offline banner; MobileNav already hides routes that require online when offline.

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

PWA service worker caches the shell + critical assets per vite.config.ts Workbox config; navigation falls back to the cached shell when offline.

Use the platform RouteErrorBoundary (src/platform/navigation/components/RouteErrorBoundary.tsx) — wraps each route module. Reports to Sentry; exposes a “Retry” + “Go home” UI.

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

MobileBreadcrumbs shows the last 2 segments of the route. Detail/edit pages set the dynamic trailing crumb via useEntityBreadcrumb(data, (e) => e.name) from @/shared/lib/hooks/useEntityBreadcrumb. Static labels come from BASE_ROUTE_LABELS in src/platform/navigation/route-labels.ts (audit: npm run audit:routes-navigation).

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

Pages MUST NOT import @/shared/ui/breadcrumb primitives directly — header auto-render is the standard.

12. Best Practices Summary

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

13. Quick Actions Pattern (PF-20)

Quick actions are not in mobile navigation. They appear on overview pages via QuickActionsSection from @/platform/dashboard/components/QuickActionsSection. The mobile More drawer surfaces a “Quick Actions” entry that opens the command palette.

14. Mobile Swipe Gestures

See Mobile Gesture Guide v2.0.0 (companion document) for the complete catalog of swipe / pinch / multi-touch hooks and components, including SwipeableCardShell, MobilePullToRefresh, useEdgeSwipe, and Phase 2 user preferences.

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

Document status: Active Maintained by: Platform Team Last reviewed: 2026-04-19

​Overview

​Quick Reference

​Component map (current)

​Context-aware bottom navigation (2026-Q2)

​Common patterns

​Key requirements

​Common issues

​CSS Variables (Single Source of Truth)

​1. Architecture

​2. Bottom Navigation

​Platform MobileNav

​Core-level BottomTabBar (new)

​Stacking with the platform nav

​3. More Drawer (MobileNavMore + MobileNavDockSheetContent)

​4. Safe Area Insets

​Test devices

​5. Touch Targets

​6. Mobile-Component Location Convention (new)

​7. Edge Swipe Back Navigation (updated)

​8. Offline Navigation

​9. Navigation Error Boundaries

​10. Testing Checklist

​Functional

​Safe areas

​Touch targets

​Accessibility

​Hydration / first paint

​Cross-browser

​11. Mobile Breadcrumbs

​12. Best Practices Summary

​13. Quick Actions Pattern (PF-20)

​14. Mobile Swipe Gestures

​15. References