Centrim Design System — a token-first, accessible React component system.

Navigation & Wayfinding

Tabs, segmented control, breadcrumbs, pagination, sidebar, top navigation, groups, collapsed rails and mobile patterns — one consistent set of V2 interaction states.

What is this?

The V2 navigation family answers three questions on every screen: where am I, what else is here, and how do I get back. Each component owns one of those jobs, and none of them duplicates another.

When to use it

Sidebar and Top Navigation for moving between modules.
Tabs for sections of one record; Segmented Control for views of one dataset.
Breadcrumbs for depth and back-navigation; Pagination for long result sets.

How to use it

Signal the active state with weight, surface and an indicator together.
Group destinations with quiet headings, not boxes or heavy dividers.
Keep counts in Badges and icons in Lucide at the standard icon sizes.

What to avoid

Building a second Pagination, Tooltip, Overlay or Button.
Letting Tabs and Segmented Control look interchangeable.
Shrinking the desktop sidebar to serve as mobile navigation.

Choosing a pattern

Scope decides the component — not how the option list happens to look.

Navigation components by scope and behaviour
Component	Scope	Changes	Use for
Sidebar Navigation	App shell	The page	Modules: Dashboard, Residents, Services, Assets, Settings
Top Navigation	App shell	The page	Brand, a few destinations, search, notifications, account
Tabs	One page	The panel	Sections of a record: Overview, Care plan, Activity
Segmented Control	One region	The rendering	Views of the same data: table / rows, 7 / 30 / 90 days
Breadcrumbs	One page	Nothing — it links up	Depth and return path on detail pages
Pagination	One data region	The result window	Long tables and lists
Mobile Navigation	App shell (mobile)	The page	Bottom bar for top destinations, drawer for the rest

Components

Tabs

Switches between sibling sections of one record or one workspace — each tab reveals a different panel of content while the page context stays the same.

import { Tabs, TabList, Tab, TabPanel } from "@/design-system";

When to use

A resident record split into Overview, Care plan, Activity and Documents.
Between three and seven peer sections that belong to the same page.
Where each section has enough content to stand on its own.

When not to use

For switching how the same content is rendered — use Segmented Control.
For moving between pages of the app — use Sidebar or Top Navigation.
For a single section, or for more than about seven sections.

Line tabs with icons, counts and badges

Amelia Johnson — Willow House, room 14. Admitted 4 March 2025.

Pill and enclosed variants

148 residents across 12 sites.

24 open requests, oldest raised 3 days ago.

Full-width and scrollable

Full width for two or three peers on narrow surfaces; the list scrolls horizontally instead of wrapping when the labels overflow.

Cleaning — weekly, Willow House.

Workspace summary.

Segmented Control

Switches how the same content is presented or filtered — density, date range, list versus table — without changing which content is on screen.

import { SegmentedControl, Segment } from "@/design-system";

When to use

Two to five mutually exclusive views of one dataset.
Table / card view switches on a list screen.
Short ranges such as 7 / 30 / 90 days on a dashboard.

When not to use

As primary navigation between pages or record sections.
For multi-select filters — use ToggleGroup or Chips.
For long option labels that would force the control to wrap.

Two and three or more options

With icons, and full width

Breadcrumbs

Shows where the current page sits in the hierarchy and provides one-click return to each ancestor — Home / Residents / Amelia Johnson.

import { Breadcrumb, BreadcrumbItem, BreadcrumbEllipsis } from "@/design-system";

When to use

Detail pages reached from a list: resident, service or asset records.
Any page nested two or more levels below a module root.
Alongside a page header, above the title.

When not to use

On top-level module pages that have no ancestors.
As a substitute for tabs or for primary navigation.
To show progress through a flow — use Stepper.

Single level and full trail

Collapsed intermediate levels

On narrow viewports the middle crumbs collapse so the root and the current page always stay readable.

One standard way out of a detail or sub-page: an arrow plus the name of the parent destination, so the return path is never guessed from browser history.

import { BackNavigation } from "@/design-system";

When to use

Above the header of a resident or service detail page.
On a sub-page reached from one place only, e.g. Resident activity.
In a full-page form opened from a list, to return without submitting.

When not to use

Alongside a second competing back affordance in the same workflow.
Inside a Dialog or Drawer — those close, they do not navigate.
Where the trail is more than one level deep — use Breadcrumbs instead.

Back to the parent list, and label-only form

Back to Residents Service details

Paired with breadcrumbs on a detail page

Back to Residents

Do

Name the destination — “Back to Residents”, not “Back”.
Place it once, directly above the page title.

Don't

Pair it with a second back button or a duplicate breadcrumb trail.
Use it as the only way to leave an unsaved form — guard the dismissal instead.

Pagination

Moves through pages of a list or table. This is the single Pagination implementation in the system — navigation extends it with a footer composition and a page-size control rather than replacing it.

import { Pagination, PaginationBar, PaginationPageSize } from "@/design-system";

When to use

Tables and lists longer than one page of results.
Below the data region, as the last element of the table card.
With a result summary so the user knows the size of the set.

When not to use

For fewer results than one page — hide the control entirely.
For streams and feeds where infinite scroll is the established pattern.
As navigation between unrelated pages of the app.

Page numbers with first / last

Rows-per-page control

Rows per page

Table footer composition

PaginationBar pairs the result summary and page-size control with the same Pagination component.

Showing 51–75 of 288

Rows per page

Primary navigation for the application shell: grouped destinations, nested branches, counts and a collapsible icon rail. Pass accordion to the Sidebar so only one collapsible region per sibling scope is expanded at a time — expanding another collapses the open one, and the branch containing the active page stays expanded. Open and close animate through the shared ds-collapsible utilities, and in the collapsed rail a branch icon reveals its nested destinations in a hover flyout that inherits the rail tone.

import { Sidebar, SidebarGroup, SidebarItem, SidebarCollapsibleItem, SidebarSubItem } from "@/design-system";

When to use

Products with more than five top-level destinations.
Where destinations need grouping (Overview, Management, Settings).
Where a branch has second-level pages, such as Residents → List / Details / Activity.

When not to use

For sections of one page — use Tabs.
On mobile: use the drawer or bottom bar instead of a shrunken sidebar.
For actions — the sidebar navigates, it does not perform work.

Centrim Life application navigation

The full application menu: Main and Community groups, module branches (CRM, Lifestyle, Communication, Dining) with nested sub-menus, and the system entries pinned to the footer. Use the footer toggle to switch between the expanded and collapsed rail.

Main

Modules

Community

Status dots and quiet counts

Pinned or favourited destinations use the SidebarItem dot prop; nested items take a quiet meta count.

Navigation item states
State	Treatment	Non-colour carrier
default	Muted foreground, tokenised icon, transparent surface	—
hover	Raised sidebar-hover fill, foreground brightens	Pointer affordance only
active	sidebar-active fill, left indicator bar, medium weight	aria-current="page" + indicator bar + weight
focus	V2 sidebar focus ring (2px, sidebar-border-focus)	Ring is keyboard-only
disabled	Dimmed foreground and icon, normal weight, no pointer events	disabled attribute, removed from activation
expandable	Trailing chevron rotates from -90° to 0°	aria-expanded + aria-controls
collapsed + count	Icon-only row with an indicator dot on the icon	Label kept as screen-reader text; branch icons open a tone-matched flyout

Sidebar structural specification
Property	Value	Notes
width (expanded)	w-64	Labels stay readable; long labels truncate, never overflow
width (collapsed)	w-16	Icons centred, labels become screen-reader text; branches use a hover flyout
item height	min-h-9, 44px on coarse pointers	Rows grow instead of overlapping neighbours
icon size	--size-icon-sm	One leading icon per primary item
chevron size	--size-icon-xs	Single expand indicator, no alternatives
label type	text-body-sm / medium when active	Nunito throughout
group heading	text-label-sm, muted	Subordinate to items
radius	rounded-md	Same radius as Button and IconButton

Do

Keep the sidebar as the primary navigation and the top bar for context and utilities.
Give every primary item exactly one leading Lucide icon at the same token size.
Use the existing Badge component for counts, and let the collapsed rail show the indicator dot on the icon.
Group destinations with SidebarGroup headings, and nest deeper pages in SidebarCollapsibleItem.
Switch to the drawer pattern on mobile instead of shrinking the rail.

Don't

Don't style individual items one-off or tune their padding by hand.
Don't signal the current page with colour alone — the indicator bar, weight and aria-current carry it.
Don't build a sidebar-specific badge, tooltip or focus ring.
Don't let the hover fill read as strongly as the active fill.
Don't hide labels without screen-reader text, and never clip them.

The application header: the Centrim Life brand lockup, the property context the workspace is scoped to, global search, the header actions and the account control \u2014 one 64px band that lines up with the dark sidebar.

import { TopNavigation, TopNavigationBrand, ContextSelector, GlobalSearch, HeaderAction, ProfileMenu } from "@/design-system";

When to use

As the app shell header, above the sidebar and page content.
For workspace-wide context and utilities: property, search, calendar, notifications, account.
As the only navigation when the product has five or fewer destinations.

When not to use

To repeat the destinations already listed in the sidebar at full depth.
For page-level actions — those belong in the page header or action bar.
For deep hierarchies — nest those in the sidebar instead.

Anatomy: brand, context, search, actions, profile

Centrim Life

With promoted destinations

Centrim Life

Notification counts: 1\u20139, 10\u201399, 99+

Context selector states

Top Navigation anatomy
Part	Component	Responsive behaviour
Brand	TopNavigationBrand	Mark always visible; wordmark hides below sm when compact
Context	ContextSelector	Hidden below sm — context moves into the mobile drawer
Destinations	TopNavigationLink	Visible from md up; the sidebar and drawer carry them below
Search	GlobalSearch	Bounded field from sm up; collapses to one icon button on mobile
Actions	HeaderAction	40px ghost controls, 4px rhythm, identical icon size and weight
Account	ProfileMenu	Avatar only below lg; name, role and chevron from lg up

Interaction states
State	Treatment
Default	Transparent control on bg-surface; text-text-secondary icons
Hover	bg-surface-hover, border-border-strong on bordered controls
Active / pressed	bg-surface-active
Open	data-[state=open] holds the hover surface while a menu is open
Current destination	bg-primary-subtle + semibold + aria-current="page"
Focus	focus-visible:ds-focus-ring — the same ring as every other V2 control
Disabled	opacity-50, pointer events off, still announced

Why it is designed this way

The header sits above the #050B42 sidebar, so it stays a light, quiet surface: one hairline border and the smallest elevation step separate it from page content instead of a shadow stack or a tinted band. All emphasis in the chrome belongs to the sidebar.

Every header control is one height (40px) on a 4px rhythm, so brand, context, search and actions share a single optical baseline no matter which slots a screen fills.

Do

Compose the header from TopNavigationBrand, ContextSelector, GlobalSearch, HeaderAction and ProfileMenu.
Keep the action cluster to three or fewer utilities so it stays scannable.
State the current property in the context selector rather than in the page header.

Don't

Build a dashboard-specific header out of raw buttons and inputs.
Add gradients, tinted bands, large radii or a second shadow to make the header stand out.
Rely on the notification badge alone — the count belongs in the accessible name.

Compact navigation for touch: a bottom bar for the four or five most-used destinations, and a drawer for the full hierarchy.

import { MobileNavigation, MobileNavItem, MobileNavigationDrawer, MobileNavLink } from "@/design-system";

When to use

Below the md breakpoint, in place of the sidebar.
Bottom bar for the top destinations; drawer for everything else.
Where one-handed reach matters more than breadth.

When not to use

On desktop, where the sidebar and header already carry navigation.
For more than five bottom-bar destinations — move the rest into the drawer.
As a shrunken copy of the desktop sidebar.

Bottom bar

Drawer for the full hierarchy

Tabs vs Segmented Control

The two patterns are close enough to be confused, so the distinction is written down rather than left to taste.

Tabs compared with Segmented Control
	Tabs	Segmented Control
Purpose	Navigate between related content sections	Switch between related views, modes or filters
Content	Each tab reveals a different panel	The same content, rendered differently
Placement	Under the page or record header	Inside a toolbar, card header or filter bar
Count	3–7 sections	2–5 options
Example	Overview / Care plan / Activity / Documents	Table / Rows / Calendar · 7 / 30 / 90 days
Styling	Full-width capable, underline or enclosed	Compact, inset track, never full-bleed across a page

States, groups and responsive behaviour

Every navigation component uses the same interaction states, so a hover or a focus ring means the same thing wherever it appears.

Shared navigation states
State	Treatment
Default	Secondary text, transparent surface
Hover	Primary text on the hover surface token — never a colour shift alone
Focus	Shared ds-focus-ring, always visible and never removed
Active / selected	Medium weight + tinted surface + indicator bar or underline + aria-current
Disabled	Disabled text token, pointer events off, still announced
Expanded	aria-expanded=true, chevron rotated, children revealed with the ds-collapsible animation
Collapsed	Icon only, label kept as screen-reader text; branches open a tone-matched hover flyout

Responsive navigation behaviour
Breakpoint	Primary navigation	Secondary navigation
Desktop (≥ 1280px)	Expanded sidebar with groups and nesting	Tabs, breadcrumbs, segmented control at full width
Tablet (768–1279px)	Collapsed icon rail with hover flyouts for branches	Tabs scroll horizontally; breadcrumbs collapse the middle
Mobile (< 768px)	Bottom bar plus drawer	Full-width tabs or scrolling tabs; pagination stacks above the page-size control

Sidebar / Side Navigation colour

The rail keeps a dark navy identity in both themes, so it owns a small set of component-scoped semantic tokens. The background is the exact brand navy (#050B42); state fills and content resolve to the locked blue or neutral ramps — no per-component hex.

Sidebar colour tokens and their usage
Token	Utility	Used for
--color-sidebar	bg-sidebar	Rail background — brand navy #050B42, never pure black
--color-sidebar-hover	hover:bg-sidebar-hover	Hover fill, one step up the same navy ramp
--color-sidebar-active	bg-sidebar-active	Active destination fill
--color-sidebar-foreground	text-sidebar-foreground	Item label at rest on hover, and nested active labels (18.5:1)
--color-sidebar-foreground-muted	text-sidebar-foreground-muted	Group headings and inactive item labels (12.8:1)
--color-sidebar-foreground-active	text-sidebar-foreground-active	Active item label on the active fill (12.8:1)
--color-sidebar-foreground-disabled	text-sidebar-foreground-disabled	Disabled destinations — dimmer hue, no opacity fade (7.2:1)
--color-sidebar-icon	[&_svg]:text-sidebar-icon	Lucide icons at the standard sidebar icon size
--color-sidebar-icon-active	[&_svg]:text-sidebar-icon-active	Icon inside the active destination
--color-sidebar-indicator	bg-sidebar-indicator	Active indicator bar and nested active border (9.3:1 on the rail)
--color-sidebar-border	border-sidebar-border	Footer divider, group divider on the collapsed rail, nested rail
--color-sidebar-border-focus	ds-sidebar-focus-ring	Keyboard focus outline, recoloured for the navy background

Sidebar colour behaviour by mode and state
Concern	Behaviour
Light mode	The rail stays navy — it is not flipped to white just because the application canvas is light
Dark mode	Same navy background by design, not an inversion; only the divider and focus ring switch to their dark-theme counterparts
Active state	Never colour alone: aria-current="page", medium weight, raised fill and an indicator bar
Hover	Stays inside the navy family — a fill change, not a hue change
Focus	ds-sidebar-focus-ring: 2px outline with a 2px offset, visible on navy and never removed
Disabled	A dimmer navy-safe foreground that still clears 4.5:1, plus pointer-events off; opacity is not used to signal it
In-page section nav	tone="surface" opts a nav inside page content back onto the surface/text tokens, so it inherits the card it sits in

Rules

Do

Group destinations under quiet, uppercase-free headings: Overview, Management, Settings.
Combine weight, surface and an indicator for the active item so it survives greyscale.
Keep Lucide icons at the standard --size-icon-sm rail size and align them on one axis.
Give collapsed rails a visually-hidden label, and reveal nested branches in the rail-toned hover flyout.
Pair Residents → list → details → activity with breadcrumbs so the way back is always visible.

Don't

Do not build another Pagination, Tooltip, Drawer or Button for navigation.
Do not use a Segmented Control as primary navigation, or Tabs as a filter.
Do not rely on colour alone, or add heavy borders and boxes around groups.
Do not truncate labels in the collapsed rail — keep them as screen-reader text and use the flyout.
Do not introduce new semantic colours or arbitrary spacing for a one-off nav style.

Why it is designed this way

Navigation is the part of the system users touch on every screen, so it is built entirely from components that already exist: Badge for counts, Tooltip and Drawer from the overlay system, IconButton for compact controls, and the single Pagination implementation from the data-display family. Navigation adds composition — PaginationBar, SidebarCollapsibleItem — never a parallel implementation.

Active state is deliberately over-specified: weight, surface, indicator and aria-current together. That keeps wayfinding legible in dark mode, in greyscale and for screen-reader users, and it means no screen needs to invent its own emphasis to make the current page obvious.