Site and editorial

Documentation layout

<forma-documentation-layout>

Documentation page: navigation rail, prose article, and optional outline; navigation compacts to a wrapping list in narrow containers.

Authoring tag
<forma-documentation-layout>
Behavior owner
Site content
Canonical source
patterns/documentation-layout.html

Purpose

The documentation layout arranges a documentation page inside the marketing shell's main region: .forma-doc__nav (section navigation), .forma-doc__content (the article, normally with .forma-prose) and an optional .forma-doc__aside (an "On this page" outline). Three regions with different roles cannot share one minimum size, so the grid regroups by the width of .forma-site__main using container queries: one column, then navigation beside the article with the outline after the article, then all three side by side. Source order never changes. Routing, the current page and outline generation belong to the site.

Use when

  • A documentation or guide page needs section navigation and a readable article.
  • Long articles benefit from an outline of their headings.
  • The page is part of a site built on Marketing shell with data-forma-layout="documentation".

Avoid when

  • An application needs a navigation rail and a work area: use Sidebar, Rail or Workspace shell.
  • A marketing page with sections and cards: compose Hero and Section heading instead.
  • Navigation has many nested levels that need expand and collapse behavior: that requires Disclosure or application code, which this layout does not provide.

Behavior to know

  • Needs an .forma-site__main ancestor, because that element is the forma-main container the layout queries; without it the layout stays one column.
  • Navigation and outline lists are ruled rails with 44px link rows; the current page is marked by aria-current with a strong rule and bold text.
  • Inside .forma-doc__content the h1 is reduced to the h2 size so the article title does not dominate the page.
  • On wide, tall viewports the navigation and outline stick below the header and scroll independently when longer than the viewport.

Basic example

The smallest correct markup: the canonical pattern from patterns/documentation-layout.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal documentation layout

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.

Install

Documentation pages pair a navigation rail with a prose article and an optional page outline.

HTML · Minimal documentation layout Raw HTML for HTML · Minimal documentation layout
<forma-documentation-layout class="forma-component-tag">
<div class="forma-site" data-forma-layout="documentation">
  <div class="forma-site__main">
  <div class="forma-doc">
    <nav class="forma-doc__nav" aria-label="Documentation">
      <p class="forma-eyebrow forma-doc__heading">Guides</p>
      <ul><li><a href="#install" aria-current="page">Install</a></li><li><a href="#configure">Configure</a></li><li><a href="#upgrade">Upgrade</a></li></ul>
    </nav>
    <article class="forma-doc__content forma-prose" id="install">
      <h1>Install</h1>
      <p>Documentation pages pair a navigation rail with a prose article and an optional page outline.</p>
    </article>
    <nav class="forma-doc__aside" aria-label="On this page">
      <p class="forma-eyebrow forma-doc__heading">On this page</p>
      <ul><li><a href="#install">Requirements</a></li><li><a href="#install">Verify</a></li></ul>
    </nav>
  </div>
  </div>
</div>
</forma-documentation-layout>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Article without an outline

A short reference page with navigation and an article only. Without an aside, the article fills the remaining columns at every width. Examples use h2 for the article title because the catalog page already has an h1.

Live demo. 3 native actions work here and are verified by an outcome test.

Surface tones

Set data-forma-tone to surface, elevated or inverse on a region. Text, links, labels and rules inside adapt automatically.

HTML · Article without an outline Raw HTML for HTML · Article without an outline
<forma-documentation-layout class="forma-component-tag">
  <div class="forma-site" data-forma-layout="documentation">
    <div class="forma-site__main">
      <div class="forma-doc">
        <nav class="forma-doc__nav" aria-label="Reference">
          <p class="forma-eyebrow forma-doc__heading">Reference</p>
          <ul><li><a href="#documentation-layout-article-without-outline-tokens">Tokens</a></li><li><a href="#documentation-layout-article-without-outline-tones" aria-current="page">Surface tones</a></li><li><a href="#documentation-layout-article-without-outline-tokens">Breakpoints</a></li></ul>
        </nav>
        <article class="forma-doc__content forma-prose" id="documentation-layout-article-without-outline-tones">
          <h2>Surface tones</h2>
          <p id="documentation-layout-article-without-outline-tokens">Set <code>data-forma-tone</code> to <code>surface</code>, <code>elevated</code> or <code>inverse</code> on a region. Text, links, labels and rules inside adapt automatically.</p>
        </article>
      </div>
    </div>
  </div>
</forma-documentation-layout>

Click or tap the code once to select all of it, then copy.

Scenario

Long guide with outline

A guide with several navigation groups and an outline of its headings. The outline follows the article in source order; it moves beside the article only when the main region is at least 72rem wide.

Live demo. 8 native actions work here and are verified by an outcome test.

Upgrade Forma

Nothing upgrades automatically. Each upgrade is one reviewable change.

Read the release notes

Read the notes for every version between yours and the target.

Update the lock

Change the version in forma.lock and run the installer with --update.

Verify

Run the site checks, then commit the lock with any markup changes.

HTML · Long guide with outline Raw HTML for HTML · Long guide with outline
<forma-documentation-layout class="forma-component-tag">
  <div class="forma-site" data-forma-layout="documentation">
    <div class="forma-site__main">
      <div class="forma-doc">
        <nav class="forma-doc__nav" aria-label="Guides">
          <p class="forma-eyebrow forma-doc__heading">Start</p>
          <ul><li><a href="#documentation-layout-long-guide-article">Install</a></li><li><a href="#documentation-layout-long-guide-article" aria-current="page">Upgrade</a></li></ul>
          <p class="forma-eyebrow forma-doc__heading">Operate</p>
          <ul><li><a href="#documentation-layout-long-guide-article">Local CSS policy</a></li><li><a href="#documentation-layout-long-guide-article">Deploy to GitHub Pages</a></li><li><a href="#documentation-layout-long-guide-article">Test before deployment</a></li></ul>
        </nav>
        <article class="forma-doc__content forma-prose" id="documentation-layout-long-guide-article">
          <h2>Upgrade Forma</h2>
          <p>Nothing upgrades automatically. Each upgrade is one reviewable change.</p>
          <h3 id="documentation-layout-long-guide-notes">Read the release notes</h3>
          <p>Read the notes for every version between yours and the target.</p>
          <h3 id="documentation-layout-long-guide-lock">Update the lock</h3>
          <p>Change the version in <code>forma.lock</code> and run the installer with <code>--update</code>.</p>
          <h3 id="documentation-layout-long-guide-verify">Verify</h3>
          <p>Run the site checks, then commit the lock with any markup changes.</p>
        </article>
        <nav class="forma-doc__aside" aria-label="On this page: Upgrade Forma">
          <p class="forma-eyebrow forma-doc__heading">On this page</p>
          <ul><li><a href="#documentation-layout-long-guide-notes">Read the release notes</a></li><li><a href="#documentation-layout-long-guide-lock">Update the lock</a></li><li><a href="#documentation-layout-long-guide-verify">Verify</a></li></ul>
        </nav>
      </div>
    </div>
  </div>
</forma-documentation-layout>

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

Phone compact navigation

At phone width the navigation becomes a short wrapping row above the article, and the outline follows the article.

Live demo. 5 native actions work here and are verified by an outcome test.

Viewport width

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

What changes at narrow widths

  • Below a 48rem main-region width the layout is one column in source order: navigation, article, outline.
  • Below a 48rem layout width the navigation list wraps like a cluster with a bottom rule, and the current page is marked by a bottom rule instead of a side rule, so the article is not pushed below the fold.
  • Every navigation and outline link keeps a 44px minimum row height for touch.
  • Rails are not sticky below 64rem viewport width or 36rem height, so nothing overlays the article on phones in either orientation.
HTML · Phone compact navigation Raw HTML for HTML · Phone compact navigation
<forma-documentation-layout class="forma-component-tag">
  <div class="forma-site" data-forma-layout="documentation">
    <div class="forma-site__main">
      <div class="forma-doc">
        <nav class="forma-doc__nav" aria-label="Documentation sections">
          <p class="forma-eyebrow forma-doc__heading">Guides</p>
          <ul><li><a href="#documentation-layout-mobile-compact-nav-article" aria-current="page">Install</a></li><li><a href="#documentation-layout-mobile-compact-nav-article">Configure</a></li><li><a href="#documentation-layout-mobile-compact-nav-article">Upgrade</a></li><li><a href="#documentation-layout-mobile-compact-nav-article">Deploy</a></li></ul>
        </nav>
        <article class="forma-doc__content forma-prose" id="documentation-layout-mobile-compact-nav-article">
          <h2>Install</h2>
          <p>Create <code>forma.lock</code>, then install the pinned assets with the release installer.</p>
          <h3 id="documentation-layout-mobile-compact-nav-verify">Verify</h3>
          <p>The installer fails when any file differs from its recorded checksum.</p>
        </article>
        <nav class="forma-doc__aside" aria-label="On this page: Install">
          <p class="forma-eyebrow forma-doc__heading">On this page</p>
          <ul><li><a href="#documentation-layout-mobile-compact-nav-verify">Verify</a></li></ul>
        </nav>
      </div>
    </div>
  </div>
</forma-documentation-layout>

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-labelnav.forma-doc__nav, nav.forma-doc__asidestring—Names each navigation landmark distinctly, for example "Documentation" and "On this page".
aria-currenta in .forma-doc__navpageabsentMarks the current page in the navigation with a strong rule and bold text.
data-forma-layout.forma-sitedocumentation—Declares the page type on the shell; the layout itself does not depend on it.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-docBlock class—Grid root and forma-doc size container. One column by default; two columns (navigation 11 to 15rem, article) when .forma-site__main is at least 48rem; three (plus a 10 to 14rem outline) at 72rem.
.forma-doc__asideElement class—Optional page outline. Follows the article below 72rem and sits in the third column above it; sticky like the navigation.
.forma-doc__contentElement class—The article column. Combine with forma-prose. Reduces h1 to the h2 size.
.forma-doc__headingElement class—Group label above a navigation or outline list; combine with forma-eyebrow.
.forma-doc__navElement class—Section navigation. Its lists are ruled rails with 44px link rows; compacts to a wrapping row when the layout is narrower than 48rem. Sticky with its own scrolling at 64rem wide and 36rem tall viewports.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through navigation links, then the article, then the outline, in source order at every width.
EnterFollows the focused link; outline links jump to headings in the article.

States

Documentation layout states
StateHow it is expressedPresentation
One column@container forma-main below 48remNavigation, article and outline stack in source order.
Two columns@container forma-main (inline-size >= 48rem)Navigation beside the article; the outline sits under the article in the second column.
Three columns@container forma-main (inline-size >= 72rem)Navigation, article and outline side by side.
Compact navigation@container forma-doc (inline-size < 48rem)Navigation lists wrap horizontally; the current link gets a bottom rule.
Current pagearia-current on a navigation linkStrong rule and bold text.
Sticky rails@media (min-width: 64rem) and (min-height: 36rem)Navigation and outline stick below the header and scroll within the viewport height.

Accessibility

Forma provides

  • Regroups with container queries without reordering, so reading and focus order are the same at every width.
  • Keeps navigation and outline links at a 44px minimum row height with visible focus.
  • Marks the current page with a rule and bold weight in addition to aria-current.
  • Makes rails sticky only where there is room, so they never cover the article.

Your application supplies

  • Label the navigation and outline landmarks distinctly and mark the current page with aria-current="page".
  • Generate outline links from the article's real headings and keep their ids stable.
  • Keep one h1 per page, normally the article title.

Responsive behavior

  • Regroups by the main region's width (forma-main container at 48rem and 72rem), not the viewport, so it adapts correctly inside narrower frames.
  • Below a 48rem layout width (forma-doc container) the navigation compacts into a wrapping row.
  • All columns have min-inline-size: 0; long words and code in the article wrap or scroll inside their own blocks.
  • Rails stick only at min-width: 64rem and min-height: 36rem, with a maximum height of the viewport minus the header offset.

Motion

  • No animation: regrouping is immediate. Outline and navigation jumps scroll smoothly only under prefers-reduced-motion: no-preference (a shell rule) and instantly otherwise.

Usage guidance

Do

  • Keep navigation groups short and labelled with forma-doc__heading.
  • Include an outline only for articles long enough to need one.

Avoid

  • Hiding the navigation behind a toggle at narrow widths; it compacts instead.
  • Placing the layout outside .forma-site__main, which disables its regrouping.

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.