Navigation & layout

The page-scaffolding primitives. PageHeader, Eyebrow, Breadcrumbs, and Divider are presentational (render server-side). Tabs and Pagination are interactive islands. Astro layout twins are also exported at @repo/ui/PageHeader.astro, @repo/ui/PageShell.astro, and @repo/ui/Logo.

PageHeader

Inbox

Order intake

Triage incoming purchase orders and route them for review.

import { PageHeader } from '@repo/ui/nav';

<PageHeader eyebrow="Inbox" title="Order intake" description="…" actions={<Button>New</Button>} />

Orange Eyebrow, ink title, muted description, optional right-aligned actions. Use Eyebrow on its own for the all-caps tracked label anywhere.

Breadcrumbs

1. Orgs/
2. Acme Foods/
3. Billing

items: { label, href? }[] — the last is the current page (aria-current="page"); earlier items link.

Tabs & Pagination

ActiveArchivedDeleted

12 orders in progress.

‹1234…20›

• Tabs — tabs: { id, label, content }[], controlled (value) or uncontrolled (defaultValue). Radix-backed: roving tabindex, arrow-key nav, ARIA tablist/tab/tabpanel. Active tab carries the orange underline.
• Pagination — page, totalPages, onPageChange, siblingCount?. Ellipsis gaps, disabled ends, aria-current on the active page.

AppShell & RailNav

The cockpit frame: a dark RailNav (icon strip, tooltips when collapsed, orange active state) on the left, a bright workspace on the right via AppShell. Click a rail icon to switch.

DB

inbox

Order intake

Triage incoming orders and route them for review.

New order

Today

128

+12%

Errors

0.4%

-0.2pt

Awaiting

9

review

import { AppShell, RailNav } from '@repo/ui/nav';

<AppShell sidebar={
  <RailNav activeId={route} logo={<Logo/>} footer={<UserMenu/>} items={[
    { id: 'inbox', label: 'Inbox', href: '/inbox', icon: <InboxIcon className="h-5 w-5" /> },
  ]} />
}>
  {pageContent}
</AppShell>

RailNav is always a dark surface; pass expanded to show labels (224px) instead of the 56px icon strip. Icon-only items get an aria-label + a Tooltip.

How apps/webapp Wires AppShell, CockpitShell, and the 3-Pane Surfaces

In apps/webapp, the legacy Sidebar.astro and unified_shell_v2 feature flag have been retired. Every authenticated route renders inside ShellFrame.astro (apps/webapp/src/components/layout/ShellFrame.astro), which mounts the dark 56px AppRail.astro (RailNav.tsx wrapping @repo/ui’s RailNav, seeded from Astro.locals with capability-gated and Flagsmith-gated items plus the account/org switcher) on the left and the workspace <slot /> on the right:

1. Standard Scrollable Pages (Layout.astro → components/navigation/AppShell.astro):
   • Uses <ShellFrame scroll="auto"> (<main id="main-content" class="flex-1 overflow-y-auto bg-[var(--om-bg)]">) plus ToastContainer, HelpDrawer, NotificationsDrawer, and the ⌘K CommandPalette.
   • Used by /settings, /customers, /analytics, /team, /admin/*, etc.
2. Full-Bleed 3-Pane Cockpit Pages (CockpitShell.astro):
   • Uses <ShellFrame scroll="hidden"> (<main id="main-content" class="flex flex-1 flex-col overflow-hidden bg-[var(--om-bg)]">) with Astro ClientRouter soft navigation and independent per-pane scrolling:
     • Unified Inbox (/inbox → InboxCockpit.tsx):
       1. Left Rail (56px): AppRail.astro / RailNav.tsx
       2. Center Queue List Pane: Virtualized/paginated CockpitRow list with queue tabs (Mine, Available, Branch), lifecycle views (active | archived | deleted), status filters (needs_review, needs_fix, processing, ready, failed), bulk actions, and Superhuman-style keyboard navigation (j/k, e, Enter, /).
       3. Right Detail & Preview Pane (CockpitDetail.tsx + CockpitItemPreview.tsx): Inline PDF/spreadsheet/email preview, PO metadata, AuroraRoutingCard, and state-aware SubmitButton / “Full review” action.
     • Order Review Workbench (/orders/pdf/[documentId]/review → ReviewResponsiveBody.tsx):
       • Desktop (>= 768px) renders a 3-pane CSS Grid (grid-template-columns: 280px minmax(320px, 1fr) minmax(0, 1.5fr)) above ReadinessFooter.tsx (auto 1fr auto grid; phones < 768px switch panes via ReviewMobileTabs):
       1. Pane 1 (280px left) — ReviewIssuesRail.tsx: Order header metadata, customer & ship-to resolution cards, PoNumberInput / PoHistoryStrip, and the prioritized issue/revision list (Needs attention, Changes, Unchanged).
       2. Pane 2 (minmax(320px, 1fr) center) — ReviewCenterPane.tsx + RevisionPanel.tsx: Line-item table, MismatchDecisionCard, LineOverrideEditor, DiscountMatchPanel, QuoteSplitPanel, and ERPSearchModal.
       3. Pane 3 (minmax(0, 1.5fr) right) — ReviewDocViewer.tsx: Synchronized source document viewer (PDFViewerWithHighlights with bounding-box highlights, SpreadsheetFullView, CSVPreview, ImageViewerWithHighlights, EmailPreview, TextPreview, AudioPreview).

Divider

Above

Below

orientation (horizontal|vertical), decorative (default true). On Radix Separator.

Accessibility

• Breadcrumbs/Pagination are landmark navs with labels; Tabs uses the full ARIA tab pattern via Radix. Verified with jest-axe; the pagination ellipsis algorithm is unit-tested.