Navigation

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

Behavior to know

  • Grid of var(--forma-navigation-width) (default minmax(11rem, 16rem)) and a minmax(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.

Canonical

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.

HTML · Minimal navigation shell Raw HTML for HTML · Minimal navigation shell
<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

Scenario

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.

Settings navigation
HTML · Project settings area Raw HTML for HTML · Project settings area
<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.

Scenario

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.

Reports navigation
HTML · Narrower navigation column Raw HTML for HTML · Narrower navigation column
<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.

Mobile example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Compact navigation on a phone Raw HTML for HTML · Compact navigation on a phone
<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.

Baseline

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelboth nav elementsthe same string—Names the navigation landmark. Use the same label on both, because only one is displayed at a time.
aria-currentlinkpageabsentMarks the current destination. Set it identically in both lists.
opendetails.forma-navigation-shell__compactbooleanabsent (closed)Native disclosure state in compact mode. The browser toggles it; the application may close it after navigation.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-navigation-shellBlock class—Root grid: navigation column and content column above 48rem; a single column at or below it.
.forma-navigation-shell__compactElement class—Native details disclosure shown at or below 48rem; its summary is a 44px row.
.forma-navigation-shell__contentElement class—The content region (normally the page's main element). It can shrink to avoid overflow.
.forma-navigation-shell__persistentElement class—Side-column nav shown above 48rem as a vertical list of links.
--forma-navigation-widthCustom property—Width track of the navigation column. Default minmax(11rem, 16rem).
--forma-navigation-spaceCustom property—Gap between navigation and content. Default 1rem.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the visible navigation links, then into the content.
Enter / Space on summaryOpens or closes the compact disclosure (native details behavior).
Enter on a linkFollows the link (native).
Events
EventDescription
toggleNative event fired by the compact details when it opens or closes.

Form behavior

Does not participate in forms.

States

Navigation shell states
StateHow it is expressedPresentation
Persistentviewport wider than 48remSide-column nav visible; compact disclosure hidden.
Compact closedviewport 48rem or narrower, details without openOnly the Navigation summary row is visible above the content.
Compact openopen on detailsDestinations listed vertically under the summary.
Current destinationaria-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) with min-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.