Install
Documentation pages pair a navigation rail with a prose article and an optional page outline.
<forma-documentation-layout>
Documentation page: navigation rail, prose article, and optional outline; navigation compacts to a wrapping list in narrow containers.
<forma-documentation-layout>patterns/documentation-layout.htmlThe 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.
data-forma-layout="documentation"..forma-site__main ancestor, because that element is the forma-main container the layout queries; without it the layout stays one column.aria-current with a strong rule and bold text..forma-doc__content the h1 is reduced to the h2 size so the article title does not dominate the page.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.
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.
Documentation pages pair a navigation rail with a prose article and an optional page 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="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.
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.
Set data-forma-tone to surface, elevated or inverse on a region. Text, links, labels and rules inside adapt automatically.
<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.
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.
Nothing upgrades automatically. Each upgrade is one reviewable change.
Read the notes for every version between yours and the target.
Change the version in forma.lock and run the installer with --update.
Run the site checks, then commit the lock with any markup changes.
<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.
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.
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.
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 | nav.forma-doc__nav, nav.forma-doc__aside | string | — | Names each navigation landmark distinctly, for example "Documentation" and "On this page". |
aria-current | a in .forma-doc__nav | page | absent | Marks the current page in the navigation with a strong rule and bold text. |
data-forma-layout | .forma-site | documentation | — | Declares the page type on the shell; the layout itself does not depend on it. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-doc | Block 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__aside | Element class | — | Optional page outline. Follows the article below 72rem and sits in the third column above it; sticky like the navigation. |
.forma-doc__content | Element class | — | The article column. Combine with forma-prose. Reduces h1 to the h2 size. |
.forma-doc__heading | Element class | — | Group label above a navigation or outline list; combine with forma-eyebrow. |
.forma-doc__nav | Element 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. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through navigation links, then the article, then the outline, in source order at every width. |
| Enter | Follows the focused link; outline links jump to headings in the article. |
| State | How it is expressed | Presentation |
|---|---|---|
| One column | @container forma-main below 48rem | Navigation, 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 page | aria-current on a navigation link | Strong 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. |
aria-current.aria-current="page".h1 per page, normally the article title.forma-main container at 48rem and 72rem), not the viewport, so it adapts correctly inside narrower frames.forma-doc container) the navigation compacts into a wrapping row.min-inline-size: 0; long words and code in the article wrap or scroll inside their own blocks.min-width: 64rem and min-height: 36rem, with a maximum height of the viewport minus the header offset.prefers-reduced-motion: no-preference (a shell rule) and instantly otherwise.forma-doc__heading..forma-site__main, which disables its regrouping.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.