Breadcrumb Implementation Guide

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

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)

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

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

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

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

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

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

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

// 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',
};

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

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

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

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

// ❌ 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',

// ❌ 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',
};

// ❌ 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.

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