Breadcrumb Implementation 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: For an overview of all navigation documentation, see NAVIGATION_GUIDE_INDEX.md

​

Overview

• Desktop: Auto-generated breadcrumbs in the header (DesktopHeader + Breadcrumbs)
• Mobile: Same trail as desktop in the fixed context row under the primary MobileHeader row (MobileBreadcrumbs). Do not render a second duplicate trail in page bodies when the shell already shows crumbs.
• Centralized policy: shouldShowBreadcrumbs / shouldShowMobileHeaderContextRow in src/platform/navigation/utils/breadcrumb-visibility.ts (keep ResponsiveNav main padding-top aligned with whether the context row is visible).
• Shared segment logic: src/platform/navigation/utils/generate-route-breadcrumb-segments.ts (desktop and mobile use the same generator).
• Centralized Labels: All route labels in route-labels.ts

​

Mobile placement contract

1. When shouldShowBreadcrumbs(pathname) is true, breadcrumbs appear only in MobileHeader’s second row (not inside scrollable main).
2. PageContainer breadcrumbs + showBreadcrumbs render only when the header policy is false for that route (avoids duplicate chrome). Prefer fixing policy/labels over in-page duplicates.
3. Two-segment module routes that still need crumbs (e.g. /ce/referral-sources, /cl/pdmp) are allowlisted in breadcrumb-visibility.ts (MODULE_TWO_SEGMENT_BREADCRUMB_ROUTES).
4. Never mount <Breadcrumbs /> inside page content; use useBreadcrumbLabel / useEntityBreadcrumb for dynamic last segments.

​

Quick Reference

​

Basic Implementation

// Automatically included in DesktopHeader
// No code needed - works automatically based on route

<MobileBreadcrumbs maxSegments={2} />

// In route-labels.ts — keys are full paths starting with `/`
export const ROUTE_LABELS: Record<string, string> = {
  '/hr/employees': 'Employees',
  '/hr/employees/:id': 'Employee Details',
  // ... more labels
};

​

Common Patterns

1. Open src/platform/navigation/route-labels.ts
2. Add entry to BASE_ROUTE_LABELS: '/route/path': 'Display Label' (Title Case)
3. Breadcrumbs automatically use the label
4. npm run audit:routes-navigation enforces 100% coverage — every <Route> must have a label

• Default shows last 2 segments
• Adjust with maxSegments prop
• Horizontal scroll for overflow

• Desktop: @/platform/navigation/Breadcrumbs.tsx
• Mobile: @/platform/navigation/MobileBreadcrumbs.tsx
• Labels: @/platform/navigation/route-labels.ts

​

1. Architecture

​

Component Structure

src/platform/navigation/
├── Breadcrumbs.tsx           # Desktop auto-generated breadcrumbs
├── MobileBreadcrumbs.tsx   # Mobile-optimized breadcrumbs (same segments as desktop)
├── route-labels.ts         # Centralized ROUTE_LABELS map (~150 routes)
├── MobileHeader.tsx        # Integrates MobileBreadcrumbs + org switcher row
└── utils/
    ├── breadcrumb-visibility.ts              # When header/context row shows crumbs
    └── generate-route-breadcrumb-segments.ts # Shared segment builder

src/shared/ui/
└── breadcrumb.tsx          # Base primitives (shadcn/ui)

src/shared/components/
└── PageContainer.tsx       # Optional breadcrumbs (suppressed when header shows auto crumbs)

​

Data Flow

1. User navigates to a route (e.g., /hr/employees/123/edit)
2. Breadcrumbs.tsx parses the pathname into segments
3. Each segment is looked up in ROUTE_LABELS
4. Breadcrumb trail is rendered with links to parent routes

​

Breadcrumb Flow Diagram

​

2. Component Reference

​

2.1 Base Primitives (@/shared/ui/breadcrumb)

​

2.2 Auto-Generated (@/platform/navigation/Breadcrumbs.tsx)

• Parses pathname into segments
• Looks up labels in ROUTE_LABELS
• Handles module context
• Falls back to formatted path segments

​

2.3 Mobile (@/platform/navigation/MobileBreadcrumbs.tsx)

• Shows last N segments
• Horizontal scroll for overflow
• 44px touch targets
• Safe area support

​

2.4 Route Labels (@/platform/navigation/route-labels.ts)

export const BASE_ROUTE_LABELS: Record<string, string> = {
  // Platform
  '/settings': 'Settings',
  '/profile': 'My Profile',

  // HR Module
  '/hr': 'Workforce',
  '/hr/employees': 'Employees',
  '/hr/employees/:id': 'Employee Details',

  // ... ~1,140 total routes
};

// Re-exported as ROUTE_LABELS for downstream consumers.
export const ROUTE_LABELS: Record<string, string> = { ...BASE_ROUTE_LABELS };

​

2.5 Hub Tab Labels (@/platform/navigation/hub-tab-labels.ts)

export const HUB_TAB_LABELS: Record<string, Record<string, string>> = {
  '/hr/ats': { dashboard: 'Dashboard', candidates: 'Candidates', /* ... */ },
  '/cl/charts/:chartId': { summary: 'Summary', notes: 'Progress Notes', /* ... */ },
};

​

2.6 Dynamic entity labels (@/shared/lib/hooks/useEntityBreadcrumb)

import { useEntityBreadcrumb } from '@/shared/lib/hooks/useEntityBreadcrumb';

const { data: employee } = useEmployeeDetail(id);
useEntityBreadcrumb(employee, (e) => e.profile?.full_name ?? 'Employee');

Coverage check: npm run audit:breadcrumb-coverage lists detail pages that don’t yet set a dynamic label so they can be migrated. Add new detail pages to this pattern by default.

​

3. Implementation Patterns

​

Pattern 1: Auto-Generated (Recommended)

// No explicit breadcrumbs needed - handled by DesktopHeader
export default function EmployeesPage() {
  return (
    <PageContainer>
      <PageHeader title="Employees" />
      <EmployeesList />
    </PageContainer>
  );
}

​

Pattern 2: Dynamic entity name via useEntityBreadcrumb (preferred for detail pages)

import { PageContainer } from '@/shared/components/PageContainer';
import { useEntityBreadcrumb } from '@/shared/lib/hooks/useEntityBreadcrumb';

export default function DocumentDetailPage() {
  const { data: document } = useDocument(id);
  useEntityBreadcrumb(document, (d) => d.title);

  return (
    <PageContainer>
      <h1>{document?.title}</h1>
      <DocumentViewer document={document} />
    </PageContainer>
  );
}

​

Pattern 3: Explicit PageContainer breadcrumbs (fallback)

<PageContainer
  breadcrumbs={[
    { label: 'Documents', href: '/documents' },
    { label: document?.title ?? 'Loading...' },
  ]}
  showBreadcrumbs
>
  ...
</PageContainer>

​

⛔ Anti-pattern: importing breadcrumb primitives directly in pages

1. The auto-generated header trail (Pattern 1)
2. useEntityBreadcrumb / useBreadcrumbLabel for dynamic entity names (Pattern 2)
3. PageContainer breadcrumbs={[…]} showBreadcrumbs for custom trails (Pattern 3)

​

4. Adding New Routes

// src/platform/navigation/route-labels.ts

const BASE_ROUTE_LABELS: Record<string, string> = {
  // ... existing labels

  // Add your new routes
  '/my-feature': 'My Feature',
  '/my-feature/:id': 'Feature Details',
  '/my-feature/sub-page': 'Sub Page',
};

​

Naming Conventions

​

Fallback Behavior

1. Takes the path segment (e.g., work-orders)
2. Replaces hyphens with spaces
3. Capitalizes the first letter of each word
4. Result: “Work Orders”

Always add an explicit label rather than relying on the fallback — audit:routes-navigation enforces 100% coverage.

​

Two-segment leaf pages (e.g. /ce/referral-sources)

​

5. Mobile Considerations

​

MobileBreadcrumbs Integration

// src/platform/navigation/MobileHeader.tsx
<header>
  {/* Logo, menu, notifications */}
</header>
<div className="border-b bg-background">
  <MobileBreadcrumbs maxSegments={2} />
</div>

​

Truncation Behavior

​

Touch Targets

• Minimum 44x44px touch area
• Adequate spacing (8px minimum between items)
• Visual feedback on touch

​

6. Accessibility

​

Required Attributes

• <nav aria-label="Breadcrumb"> on container
• <ol> for breadcrumb list (semantic ordering)
• aria-current="page" on current page item

​

Keyboard Navigation

• All links must be focusable
• Tab order follows visual order
• Focus indicators must be visible

​

Screen Readers

• “Breadcrumb, navigation”
• Each link in order
• “Current page: [Page Name]” for last item

​

7. Testing Checklist

​

Unit Tests

• Route parsing generates correct segments
• ROUTE_LABELS lookup returns expected values
• Fallback formatting works correctly
• Module context is handled

​

Integration Tests

• Breadcrumbs update on navigation
• Links navigate to correct routes
• Mobile truncation works at breakpoints

​

Accessibility Tests

• Screen reader announces structure correctly
• Keyboard navigation works
• Focus indicators visible

​

Visual Tests

• Desktop breadcrumbs render correctly
• Mobile breadcrumbs truncate properly
• Touch targets meet 44px requirement
• Safe areas respected on mobile

​

8. Common Mistakes & Anti-Patterns

​

❌ Importing breadcrumb primitives in pages

// ❌ WRONG: pages should never import @/shared/ui/breadcrumb
import { Breadcrumb, BreadcrumbList } from '@/shared/ui/breadcrumb';

// ✅ CORRECT: rely on the auto-generated header trail; for dynamic labels
//             use useEntityBreadcrumb / useBreadcrumbLabel
import { useEntityBreadcrumb } from '@/shared/lib/hooks/useEntityBreadcrumb';
useEntityBreadcrumb(employee, (e) => e.profile?.full_name);

​

❌ Detail page without a dynamic label

// ❌ WRONG: trailing crumb is the static "Employee Details" instead of the
//          employee's name. On mobile (which truncates to last 2 segments)
//          users lose entity identity entirely.
export default function EmployeeDetailPage() {
  const { data: employee } = useEmployeeDetail(id);
  return <PageContainer><EmployeeProfile employee={employee} /></PageContainer>;
}

// ✅ CORRECT: trailing crumb is the employee name
export default function EmployeeDetailPage() {
  const { data: employee } = useEmployeeDetail(id);
  useEntityBreadcrumb(employee, (e) => e.profile?.full_name ?? 'Employee');
  return <PageContainer><EmployeeProfile employee={employee} /></PageContainer>;
}

Run npm run audit:breadcrumb-coverage to see which detail pages still need this migration.

​

❌ Duplicate “Back to X” link alongside breadcrumbs

// ❌ WRONG: page already shows breadcrumbs and a top-left back-icon button
<PageContainer breadcrumbs={[...]} showBreadcrumbs>
  <Link to="/cl/in-basket"><ArrowLeft /> Back to In-Basket</Link>
  ...
</PageContainer>

// ✅ CORRECT: use DetailPageLayout backHref for the icon button; let the
//             breadcrumb provide the parent link
<DetailPageLayout backHref="/cl/in-basket" title={item.title}>
  ...
</DetailPageLayout>

​

❌ Forgetting to add route labels

// ❌ WRONG: missing from route-labels.ts → audit:routes-navigation fails

// ✅ CORRECT: add a Title Case label to BASE_ROUTE_LABELS
'/my-feature/:id': 'Feature Details',

​

❌ Inconsistent label format

// ❌ WRONG
export const BASE_ROUTE_LABELS = {
  '/hr/employees': 'employees',         // lowercase
  '/hr/employees/:id': 'Employee',      // ambiguous (singular)
};

// ✅ CORRECT
export const BASE_ROUTE_LABELS = {
  '/hr/employees': 'Employees',
  '/hr/employees/:id': 'Employee Details',
};

​

❌ Breadcrumbs on module dashboards

// ❌ WRONG: breadcrumbs render on /hr/dashboard ("HR > Dashboard") — noise

// ✅ CORRECT: shouldShowBreadcrumbs hides them automatically on top-level
//             module pages; do not override the policy on dashboards.

​

❌ Page H1 doesn’t match breadcrumb tail

// ❌ WRONG: H1 is generic, breadcrumb tail is the entity identifier
<h1>Statement Run</h1>
// breadcrumb: PM > Statement Runs > Mar 18, 2026 10:42 AM
// Mobile users (after truncation) only see the date — no context

// ✅ CORRECT: H1 includes the same identifier as the breadcrumb tail
<h1>Statement Run — {formatDate(run.run_started_at)}</h1>

​

9. Quick Reference

​

When to Show Breadcrumbs

​

File Locations

​

Audits

​

Related Documentation

​

Standards

• Constitution §6.3.1 - Breadcrumb standards and requirements

​

Navigation Guides

• Mobile Navigation Guide - Section 12: Mobile Breadcrumb Patterns
• Navigation Guide Index - Complete navigation documentation index
• Navigation Standard - Navigation patterns and policies

​

External References

• shadcn/ui Breadcrumb - Component reference