Navigation shell
<forma-navigation-shell>
Preserves current location and destination identity across persistent and compact navigation modes.
- Authoring tag
<forma-navigation-shell>- Category
- Navigation
- Behavior owner
- Application / Limen
- Canonical source
patterns/navigation-shell.html
Purpose
The navigation shell pairs a content region with primary navigation that changes form with the viewport. Above 48rem a persistent nav sits in a side column; at 48rem and below the side column is hidden and a native details disclosure labelled Navigation shows the same destinations above the content. The application renders both lists with identical destinations, order and aria-current, so the current location and each destination's identity survive the switch. Only one of the two is displayed at a time, so assistive technology meets a single navigation landmark.
Use when
- An application area has a handful of top-level destinations that should stay visible on wide screens.
- On phones the destinations should collapse behind one control without a script-driven drawer.
- The current destination must be exposed the same way in both modes.
Avoid when
- The page needs header, navigation, primary and inspector regions: use Workspace shell.
- Navigation is a modal drawer with focus trapping: use Flyout.
- The page is a public marketing site: use Marketing shell and Site header.
- Destinations are deeply nested: use Hierarchy tree inside the navigation.
Behavior to know
- Grid of
var(--forma-navigation-width)(defaultminmax(11rem, 16rem)) and aminmax(0, 1fr)content column. - Mode switch at a 48rem viewport width via a media query; there is no script.
- The compact summary is at least 44px tall and the disclosure uses native open/close behavior. The summary is a flex row, so the browser's disclosure triangle is not drawn; its text must say what it opens.
- Forma does not style
aria-current; any visual current-location cue comes from the application's link styling.
Basic example
The smallest correct markup: the canonical pattern from patterns/navigation-shell.html inside its public tag. Copy this first, then adapt labels, names and state. This component owns a page's main landmark, so it renders in its own document below.
Minimal navigation shell
Rendered from the canonical pattern file.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-navigation-shell class="forma-component-tag">
<div class="forma-navigation-shell">
<details class="forma-navigation-shell__compact">
<summary>Navigation</summary>
<nav aria-label="Primary"><a href="#overview" aria-current="page">Overview</a><a href="#activity">Activity</a><a href="#settings">Settings</a></nav>
</details>
<nav class="forma-navigation-shell__persistent" aria-label="Primary"><a href="#overview" aria-current="page">Overview</a><a href="#activity">Activity</a><a href="#settings">Settings</a></nav>
<main class="forma-navigation-shell__content" id="overview"><h1>Overview</h1></main>
</div>
</forma-navigation-shell>
Click or tap the code once to select all of it, then copy.
Examples
Project settings area
Five destinations with Access as the current page. Both lists carry the same aria-current. The content region is shown as a labelled section here; in an application it is the page's main element.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-navigation-shell class="forma-component-tag">
<div class="forma-navigation-shell">
<details class="forma-navigation-shell__compact">
<summary>Settings navigation</summary>
<nav aria-label="Project settings"><a href="#navshell-settings-general">General</a><a href="#navshell-settings-access" aria-current="page">Access</a><a href="#navshell-settings-billing">Billing</a><a href="#navshell-settings-webhooks">Webhooks</a><a href="#navshell-settings-danger">Danger zone</a></nav>
</details>
<nav class="forma-navigation-shell__persistent" aria-label="Project settings"><a href="#navshell-settings-general">General</a><a href="#navshell-settings-access" aria-current="page">Access</a><a href="#navshell-settings-billing">Billing</a><a href="#navshell-settings-webhooks">Webhooks</a><a href="#navshell-settings-danger">Danger zone</a></nav>
<section class="forma-navigation-shell__content" id="navshell-settings-access" aria-labelledby="navshell-settings-title">
<h2 id="navshell-settings-title">Access</h2>
<p>Three people and one service account can change this project.</p>
</section>
</div>
</forma-navigation-shell>
Click or tap the code once to select all of it, then copy.
Narrower navigation column
The application narrows the navigation column with the --forma-navigation-width custom property and tightens the gap with --forma-navigation-space. Long destination names wrap within the column.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-navigation-shell class="forma-component-tag">
<div class="forma-navigation-shell" style="--forma-navigation-width: minmax(8rem, 10rem); --forma-navigation-space: 0.5rem;">
<details class="forma-navigation-shell__compact">
<summary>Reports navigation</summary>
<nav aria-label="Reports"><a href="#navshell-narrow-summary" aria-current="page">Summary</a><a href="#navshell-narrow-quarterly">Quarterly incident retrospectives</a><a href="#navshell-narrow-exports">Exports</a></nav>
</details>
<nav class="forma-navigation-shell__persistent" aria-label="Reports"><a href="#navshell-narrow-summary" aria-current="page">Summary</a><a href="#navshell-narrow-quarterly">Quarterly incident retrospectives</a><a href="#navshell-narrow-exports">Exports</a></nav>
<section class="forma-navigation-shell__content" id="navshell-narrow-summary" aria-labelledby="navshell-narrow-title">
<h2 id="navshell-narrow-title">Summary</h2>
<p>Twelve reports were generated this month.</p>
</section>
</div>
</forma-navigation-shell>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Compact navigation on a phone
At phone width the persistent column is hidden and the compact disclosure appears above the content. It is shown open here so the destinations are visible.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
What changes at narrow widths
- At 48rem and below the grid becomes one column, the persistent nav is removed with display: none and the compact details is shown.
- The summary row is at least 44px tall and toggles the list natively with a tap, Enter or Space.
- Opened destinations stack vertically in the order of the persistent list; the application keeps the same aria-current.
- The disclosure stays open after a same-page link is followed; closing it on navigation is application behavior.
<forma-navigation-shell class="forma-component-tag">
<div class="forma-navigation-shell">
<details class="forma-navigation-shell__compact" open>
<summary>Account navigation</summary>
<nav aria-label="Account"><a href="#navshell-mobile-profile" aria-current="page">Profile</a><a href="#navshell-mobile-security">Security</a><a href="#navshell-mobile-notifications">Notifications</a></nav>
</details>
<nav class="forma-navigation-shell__persistent" aria-label="Account"><a href="#navshell-mobile-profile" aria-current="page">Profile</a><a href="#navshell-mobile-security">Security</a><a href="#navshell-mobile-notifications">Notifications</a></nav>
<section class="forma-navigation-shell__content" id="navshell-mobile-profile" aria-labelledby="navshell-mobile-title">
<h2 id="navshell-mobile-title">Profile</h2>
<p>Your name and photo are visible to your organization.</p>
</section>
</div>
</forma-navigation-shell>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
aria-label | both nav elements | the same string | — | Names the navigation landmark. Use the same label on both, because only one is displayed at a time. |
aria-current | link | page | absent | Marks the current destination. Set it identically in both lists. |
open | details.forma-navigation-shell__compact | boolean | absent (closed) | Native disclosure state in compact mode. The browser toggles it; the application may close it after navigation. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-navigation-shell | Block class | — | Root grid: navigation column and content column above 48rem; a single column at or below it. |
.forma-navigation-shell__compact | Element class | — | Native details disclosure shown at or below 48rem; its summary is a 44px row. |
.forma-navigation-shell__content | Element class | — | The content region (normally the page's main element). It can shrink to avoid overflow. |
.forma-navigation-shell__persistent | Element class | — | Side-column nav shown above 48rem as a vertical list of links. |
--forma-navigation-width | Custom property | — | Width track of the navigation column. Default minmax(11rem, 16rem). |
--forma-navigation-space | Custom property | — | Gap between navigation and content. Default 1rem. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through the visible navigation links, then into the content. |
| Enter / Space on summary | Opens or closes the compact disclosure (native details behavior). |
| Enter on a link | Follows the link (native). |
| Event | Description |
|---|---|
toggle | Native event fired by the compact details when it opens or closes. |
Form behavior
Does not participate in forms.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Persistent | viewport wider than 48rem | Side-column nav visible; compact disclosure hidden. |
| Compact closed | viewport 48rem or narrower, details without open | Only the Navigation summary row is visible above the content. |
| Compact open | open on details | Destinations listed vertically under the summary. |
| Current destination | aria-current="page" | Exposed to assistive technology in both modes. Forma adds no visual styling for it. |
Accessibility
Forma provides
- Displays exactly one of the two navigation elements at any width, so there is never a duplicate visible landmark.
- Uses native details for the compact mode, so expanded state and keyboard toggling come from the platform.
- Gives the compact summary a 44px target.
Your application supplies
- Render both lists with identical destinations, order and aria-current.
- Provide a visible current-location cue (for example bold or an indicator) in application styling, since Forma does not style aria-current here.
- Make persistent-mode links at least 44px tall if they are primary touch targets.
- Use a single main element for the content region and a Skip link where the navigation precedes it.
Responsive behavior
- Above 48rem: two columns, navigation width set by
--forma-navigation-width. - At 48rem and below: one column; the compact disclosure sits above the content.
- The content column is
minmax(0, 1fr)withmin-inline-size: 0, so wide content cannot push the page sideways. - The switch is viewport-based, not container-based; a narrow shell inside a wide page stays in persistent mode.
Motion
- No animation: the mode switch is a media-query change and the compact disclosure opens and closes instantly with native details.
Usage guidance
Do
- Keep top-level destinations short and stable across pages.
- Label the compact summary with a word users recognise, such as Navigation or Menu.
Avoid
- Showing different destinations in the two modes.
- Hiding the current destination only in compact mode.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.