Navigation Standard

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.

• 1.2.0 (2026-02-09): Added normative section “Tabbed Sub-Modules (Single Route + In-Page Tabs)” (§2) and “Hub and Tab UX” (§2a) with rules for sidebar behavior, breadcrumbs, quick actions, deep-link persistence, mobile tab bars, and accessibility for tabbed hubs. See §2 and §2a for details.

Navigation Documentation Index: For an overview of all navigation documentation, see NAVIGATION_GUIDE_INDEX.md
Quick Reference: For implementation tasks and quick lookup, see navigation-quick-reference.md

​

Table of Contents

1. Module Navigation Standards
2. Improvement History
3. Implementation Guidelines
4. Related Documentation

​

1. Module Navigation Standards

​

System Overview

• Module + sidebar structure (source of truth): src/platform/modules/module-registry.ts
  • Defines modules, top-level nav, grouped nav, and “sub-modules” (mini-apps).
• Desktop primary navigation is user-selectable: Dock (macOS-style), Sidebar (accordion + drill-down), or Taskbar (Windows-style); state and sidebar open/collapse are persisted via NavModeContext.
• Route components (actual pages): src/App.tsx
  • Route components must be lazy-loaded.
• Breadcrumb labels: src/platform/navigation/route-labels.ts
  • Central map used by desktop + mobile breadcrumbs.
• Mobile shortcuts catalog: src/platform/navigation/mobile-nav-config.ts
  • Defines which shortcuts can be pinned to the bottom bar / quick access.
• Permission filtering: src/platform/navigation/hooks/useNavItemPermission.ts
  • Uses PF-30 permissions when enabled, falls back to minRole.
• Route integrity tests: tests/integration/route-integrity.test.ts
  • Validates route consistency across registry, labels, and app routes.

​

Standard Definitions

​

Module

• id: hr | rh | fa | fw | fm | gr | lo
• route: default landing route (usually /{core}/dashboard)
• settingsRoute: /{core}/settings when applicable
• minRole + optional permission for PF-30

​

Nav Items (Top-Level)

• Overview / Dashboard (always)
• Forms (only if the module has module-scoped forms)
• Settings (admin-only)

​

Nav Groups (Section Navigation)

• id, label, icon
• defaultOpen (only for 1–2 groups)
• overviewRoute (optional but recommended for groups that act like “sections”)
• minRole / permission (optional, for gating entire groups)

​

Sub-Modules (Mini-Apps)

• Has a stable route prefix /{core}/{sub}/*
• Has its own “overview” route (e.g., /{core}/{sub}/dashboard)
• Has at least ~5 dedicated routes/pages
• Has its own quick actions that are meaningful within that context
• Users will benefit from “in-sub-module” sidebar mode

​

Route Conventions

• Module landing: /{core}/dashboard
• Module root: /{core} may exist but should redirect to landing (or be a label-only breadcrumb root)
• Settings: /{core}/settings
• Forms: /{core}/forms (only if module-scoped)
• Sub-modules: /{core}/{sub}/... (stable {sub} tokens)
• Create: .../new
• Edit: .../:id/edit (preferred) or .../:id + edit mode, but be consistent within a module

• /forms → Platform admin forms view (alias for /fw/forms)
• /picklists → Platform picklist management (PF-15)
• /settings → Platform settings

​

Permissions + Visibility Contract (PF-30)

• If PF-30 V2 is enabled and an item has permission, visibility is controlled by permission.
• Otherwise, visibility falls back to minRole when present.
• If neither is present, item is visible by default.

• Use permission for: admin/settings routes, approval flows, anything that mutates critical data (manage, approve, admin)
• Use minRole primarily as a fallback for: coarse “admin-only” visibility when V2 is not enabled

​

Breadcrumb Contract

• /{core} (module root label)
• /{core}/dashboard (landing)
• every route referenced by MODULE_REGISTRY.navItems[*].route
• every route referenced by MODULE_REGISTRY.navGroups[*].items[*].route
• every sub-module overviewRoute

• rely on common segment labels (details, edit) where possible, OR
• add explicit labels for the static parent route(s), and consider page-level breadcrumbs for entity names when needed

​

Mobile Shortcuts Contract

• Shortcuts should point to stable routes (dashboards, main lists, key workflows).
• Shortcut gating (minRole / permission) should not contradict the module registry’s gating.
• Sub-module shortcuts should only exist if the sub-module qualifies under the rule above.

​

Policy Decisions

​

1. Sub-Module Qualification Criteria

​

2. Tabbed Sub-Modules (Single Route + In-Page Tabs)

• Sidebar: Do not list those tab targets as separate nav items. Show one entry for the hub (Overview link to the overview route) and any separate routes (e.g. Onboarding, Offboarding) as additional items.
• Overview route is the canonical entry; tab state is encoded in the query string for shareability (e.g. /hr/ats?tab=applications).
• Quick actions may still link to specific tabs (e.g. “Job Postings” → /hr/ats?tab=postings) for power users.

​

2a. Hub and Tab UX (Tabbed Sub-Modules)

​

3. Breadcrumb Label Coverage

• navItems array
• navGroups[].items array
• Routes reachable from module navigation

• Phase 1: 80% coverage threshold (warning)
• Phase 2: 90% coverage threshold (warning)
• Phase 3: 100% coverage threshold (error, blocks merge)

​

4. Shortcut Gating Alignment

• minRole on shortcut must be ≥ module’s minRole
• permission field must match V2 permission key
• Sub-module shortcuts inherit parent module restrictions

​

5. Route Naming Conventions

• Module root: /{core}/dashboard (preferred) or /{core} (redirect only)
• Settings: /{core}/settings
• Forms: /{core}/forms (module-owned forms)
• Entity list: /{core}/{entity-plural}
• Entity new: /{core}/{entity-plural}/new
• Entity detail: /{core}/{entity-plural}/:id
• Entity edit: /{core}/{entity-plural}/:id/edit

​

6. NavGroup Guidelines

• navGroups per module: 4-8 groups (modules exceeding 8 must consolidate)
• Items per navGroup: 3-7 items (single-item groups must be merged)
• navItems (root level): 3-5 items

• Single-item groups: MUST be merged with related groups
• 2-item groups: SHOULD be merged unless functionally distinct
• Groups exceeding 8 items: SHOULD be split or promoted to sub-module

• Use noun-phrase style (e.g., “Accounts Receivable”, not “Managing Receivables”)
• Use ”&” for combined groups (e.g., “Banking & Treasury”, “Compliance & Accreditations”)
• Avoid verb-first patterns (e.g., “Close Management” → “Period Close”)

1. Overview → /{core}/dashboard
2. Forms → /{core}/forms
3. Settings → /{core}/settings (with minRole: "org_admin")

​

Icon Consistency Guidelines

📚 Complete Reference: For comprehensive icon usage rules, decision trees, and anti-patterns, see: Icon Usage Guide

​

Quick Reference

​

Icon Selection Rules

1. Semantic Meaning: Icons should semantically represent the feature or action
2. Visual Distinction: Icons should be visually distinct from other icons in the same navigation group
3. Consistency Across Modules: Similar features across modules should use similar icons

​

Anti-Patterns

• ❌ Do NOT use AlertTriangle for everything (issues, incidents, PIPs, risk)
• ❌ Do NOT use the same icon for 5+ different concepts
• ❌ Do NOT use icons without labels in navigation
• ❌ Do NOT create custom icons (use lucide-react only)
• ✅ DO check the Icon Usage Guide before adding new icons

​

Icon Audit Checklist

• Icon is unique within the navigation group
• Icon semantically represents the feature
• Icon is visually distinct from other icons in the same context
• Icon is imported from lucide-react
• Icon follows the Icon Usage Guide standards

​

Step-by-Step Standardization Plan

​

Step 0: Choose the baseline policy decisions (one-time)

• sub-module criteria (use rule above as default)
• breadcrumb label enforcement level (recommended: 100% for main nav routes)
• how shortcut gating must align with module gating
• route naming conventions (module-wide taxonomy)

​

Step 1: Inventory current module routes

• list all /{core}/* routes from src/App.tsx
• group them into 4–8 navigation groups
• identify any “legacy”/duplicate route families to deprecate

​

Step 2: Normalize the module’s route taxonomy (no new features)

• rename routes only if needed to match conventions
• ensure sub-module prefixes are stable if sub-modules exist

​

Step 3: Update module registry definition

• ensure module route is correct
• define top-level navItems (small + consistent)
• define navGroups from the IA map
• mark sub-modules only when the criteria is met
• add settingsRoute when applicable
• add/confirm minRole and permission values

​

Step 4: Align breadcrumbs

• add missing labels for all main nav routes
• remove stale labels for routes that no longer exist (or rename them)

​

Step 5: Align mobile shortcuts (optional, based on usage)

• add module/sub-module shortcuts only if they are high-traffic or high-value
• ensure gating matches the registry contract

​

Step 6: Add/strengthen guardrails

• enforce label coverage targets for navItems and navGroups.items
• (optional) validate registry routes exist in the app route table
• CRITICAL: Update KNOWN_ROUTES constant when adding new routes to ensure test coverage

​

Step 7: Rollout sequencing

1. Pilot one module closest to HR structure (often fa or rh)
2. Apply to remaining modules one-by-one
3. Final pass: ensure module switcher, breadcrumbs, and mobile all match the same contract

​

2. Improvement History

​

Consolidation History (2026-01-27)

• Phase 1 (Quick Wins): Merged FM Vendors → Operations, CE Contacts + Leads → Contacts & Leads
• Phase 2 (FA Consolidation): Merged Collections → AR, Bank Recon + Treasury → Banking & Treasury
• Phase 3 (GR Cleanup): Merged Accreditations → Compliance & Accreditations
• Phase 4 (Documentation): Created navigation audit checklist (live stub: reviews/NAVIGATION_AUDIT.md; detailed historical tables archived under docs/archive/architecture/NAVIGATION_AUDIT_CHECKLIST_full_2026-01-27.md), updated standards

​

Standardization History (2025-12-21)

• Phase 0: Policy & Documentation ✅ Complete
• Phase 1: Pilot & Infrastructure (FA) ✅ Complete
• Phase 2: Core Module Alignment (RH, FM, LO) ✅ Complete
• Phase 3: Complex Module Alignment (HR, GR) ✅ Complete
• Phase 4: Mobile Shortcuts & Permissions ✅ Complete
• Phase 5: Final Polish & 100% Enforcement ✅ Complete

• All modules aligned to standard navigation pattern
• 100% breadcrumb label coverage for registry routes
• Route integrity tests enforce 100% coverage threshold
• Mobile shortcuts configured with permission keys

​

Current Improvement Recommendations

• Reduce cognitive load through progressive disclosure
• Improve discoverability of features within large modules
• Maintain mobile-first design principles
• Integrate with permission system for access control
• Align with constitution standards for performance and accessibility

• Desktop sidebar module flyouts can be overwhelming for large modules (HR has 7 navGroups)
• Mobile sheet structure is good but could better surface sub-areas
• Overview pages not consistently linked in navigation
• Large modules (HR) need sub-area overview pages with dedicated navigation
• Collapsible sections needed in flyouts for better scanning (modules with 5+ navGroups)

• Navigation Improvements: docs/architecture/NAVIGATION_IMPROVEMENTS.md - Comprehensive recommendations for hierarchical navigation, mobile integration, and UX enhancements
• Implementation Plan: docs/NAVIGATION_IMPROVEMENT_PLAN.md - Detailed step-by-step implementation plan

​

3. Implementation Guidelines

​

Standardization Checklist

• Inventory routes - List all /{core}/* routes from src/App.tsx
• Group routes - Organize into 4-8 navigation groups
• Identify sub-modules - Apply sub-module criteria (5+ routes, stable prefix, overview route, quick actions)
• Update module registry - Add module definition to module-registry.ts
• Add breadcrumb labels - Ensure 100% coverage for all nav routes
• Configure mobile shortcuts - Add high-value shortcuts to mobile-nav-config.ts
• Update route integrity tests - Add routes to KNOWN_ROUTES in route-integrity.test.ts
• Verify permissions - Ensure permission keys match PF-30 permissions matrix
• Test navigation - Verify desktop sidebar, mobile menu, and breadcrumbs work correctly

​

Common Patterns

​

Module Definition Template

{
  id: '{core}',
  name: '{Module Name}',
  route: '/{core}/dashboard',
  settingsRoute: '/{core}/settings',
  icon: ModuleIcon,
  minRole: 'staff',
  permission: '{core}.view', // Optional, PF-30 V2
  navItems: [
    {
      label: 'Overview',
      route: '/{core}/dashboard',
      icon: LayoutDashboard,
    },
    {
      label: 'Forms',
      route: '/{core}/forms',
      icon: FileText,
      permission: 'fw.forms.view', // Module-scoped forms
    },
    {
      label: 'Settings',
      route: '/{core}/settings',
      icon: Settings,
      minRole: 'org_admin',
    },
  ],
  navGroups: [
    {
      id: '{group-id}',
      label: '{Group Label}',
      icon: GroupIcon,
      defaultOpen: false,
      overviewRoute: '/{core}/{group}/dashboard', // Optional
      isSubModule: false, // Only if meets criteria
      items: [
        {
          label: '{Item Label}',
          route: '/{core}/{group}/{item}',
          icon: ItemIcon,
          permission: '{core}.{entity}.view', // PF-30 V2
        },
      ],
    },
  ],
}

​

Sub-Module Definition Template

{
  id: '{sub-module-id}',
  label: '{Sub-Module Name}',
  icon: SubModuleIcon,
  defaultOpen: false,
  overviewRoute: '/{core}/{sub}/dashboard', // Required for sub-modules
  isSubModule: true, // Must meet all criteria
  quickActions: [ // Required for sub-modules
    {
      label: '{Action Label}',
      route: '/{core}/{sub}/{action}',
      icon: ActionIcon,
      permission: '{core}.{sub}.{action}',
    },
  ],
  items: [
    // 5+ routes required
  ],
}

​

Anti-Patterns

• Create sub-modules for groups with < 5 routes
• Use inconsistent route naming within a module
• Skip breadcrumb labels for main nav routes
• Create mobile shortcuts that contradict module permissions
• Add routes to registry without updating KNOWN_ROUTES in tests

• Follow route naming conventions consistently
• Ensure 100% breadcrumb label coverage
• Use PF-30 permission keys when available
• Test navigation on both desktop and mobile
• Update route integrity tests with new routes

​

4. Related Documentation

​

Architecture Standards

• NAVIGATION_STANDARD.md - This document
• NAVIGATION_AUDIT.md - Quarterly audit checklist
• PERMISSION_KEY_STANDARD.md - Permission key conventions
• navigation-quick-reference.md - Quick implementation reference

​

Development Guides

• Icon Usage Guide - Comprehensive icon standards and decision trees
• UI/UX Standards - UI/UX patterns
• Semantic Colors - Color token reference
• Mobile Navigation Guide - Mobile navigation patterns

​

Core References

• Platform navigation docs: src/platform/navigation/README.md
• Permissions (PF-30) patterns: src/platform/permissions/*
• Route integrity test: tests/integration/route-integrity.test.ts
• Constitution breadcrumb standards: constitution.md §6.3.1

​

Implementation Guides

• Navigation Improvements: docs/architecture/NAVIGATION_IMPROVEMENTS.md - Comprehensive recommendations
• Implementation Plan: docs/NAVIGATION_IMPROVEMENT_PLAN.md - Detailed step-by-step plan

​

Implementation Files (Source of Truth)

• Module Registry - Navigation source of truth
• Route Labels - Breadcrumb labels
• Mobile Nav Config - Mobile shortcuts

​

Related Standards

• Module Permissions Matrix: docs/module-permissions-matrix.md - Granular permissions
• Picklist system (PF-15): specs/pf/PF-15-picklist-system.md

​

Changelog