# Navigation

How a screen tells people where they are and gets them anywhere within two steps, in WerkOS on desktop and phone and on Werklist websites.

* Kind: pattern
* Page: https://design.werklist.com/patterns/navigation
* Version: 2.1.2

## When to use it

* WerkOS on a desktop: the rail for workspaces, the modules panel for modules, the module at its toolbar, tabs or a segmented control inside it, and the command palette for anything by name.
* WerkOS on a phone: the bottom bar for workspaces, the workspace screen for its modules, a module with its own bar or none, and the back arrow to leave it.
* A website: the header for sections, the section panel for pages, the side navigation for the blocks of a page, and a link to the next page at the end.

## When not to use it

* Search as the only way to a place.
* More than two levels in one navigation surface.
* A breadcrumb of pages visited.
* Hiding or disabling places because of what is on screen.

## Rules

* Mark the current place at each level at the same time, in full ink and one shape: a fill in WerkOS, an outline in a page list, a bar under a tab. Never with color alone.
* One item is marked at each level: the place you chose last.
* The place you click lights at once, before the page loads.
* Any place is within two steps: a section and a page, or a workspace and a module.
* Back returns to where you came from. Opened from a link with no history, it goes to the nearest parent, then the workspace screen, then home.
* What a person may not open is left out. A module that is coming keeps its place, marked Soon, and is not a link.
* The workspaces keep the same order on phone and desktop.
* A breadcrumb appears only inside a folder at least one level below the root, and follows the hierarchy, not the history.
* In a breadcrumb the parent folders are links in muted ink, and the current folder is text in full ink at weight 500.
* Breadcrumb separators are 14 px chevrons.
* When room runs out, the folders above the parent fold into a menu. At 360 px only the parent and the current folder show.

## States

* Loading: The navigation stays still and shows the new place. The content shows its skeleton.
* Empty workspace: The panel says in one sentence that the workspace has no modules (--text-muted)
* Missing page: The page keeps the header and the navigation

## Accessibility

* A screen reader hears the breadcrumb as a list, without the chevrons, and hears which folder is current.

## Tokens

* --type-nav
* --text
* --text-muted
* --nav-fill-active
* --nav-tab-chip
* --focus-ring