Site and editorial

Site header

<forma-site-header>

Identity and primary navigation that wraps instead of hiding links, keeps 44px targets, and marks the current page with a non-color rule.

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

Purpose

The site header is the banner row of a marketing site: a brand link (decorative mark plus a visible name), an optional tagline, and a native nav list of primary destinations. Links are ordinary anchors, so routing and current-page state belong to the site. Forma supplies the wrapping layout, 44px targets, the current-page under-rule driven by aria-current, a single emphasized action link, and the sticky behavior where it is safe.

Use when

  • A marketing, product or documentation page inside Marketing shell needs identity and a small set of primary destinations.
  • One destination is the site's main conversion (Get started, Get in touch) and should read as an action.
  • The current page or section must be visible without relying on color.

Avoid when

  • An application needs persistent, collapsible or compact navigation: use Navigation shell or Sidebar.
  • The site has more than about seven primary destinations; wrapping reaches three lines (GAP-MKT-10). Move secondary destinations to the page or Site footer.
  • Showing in-page section links for a long article: use the outline region of Documentation layout.

Behavior to know

  • Navigation wraps onto more lines instead of collapsing into a hidden menu; there is no script.
  • The brand name never hides; the decorative mark is aria-hidden, so the name is the link's accessible name.
  • The tagline is supplementary and yields below a 56rem header width to keep navigation to two lines.
  • Hover and current state use an under-rule; the action link uses the tone's action colors and a border in forced colors.

Basic example

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

Canonical

Minimal site header

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.

Example / Product

Evidence-driven engineering systems

HTML · Minimal site header Raw HTML for HTML · Minimal site header
<forma-site-header class="forma-component-tag">
<div class="forma-site">
  <header class="forma-site-header">
    <div class="forma-site-header__inner">
      <div class="forma-site-header__identity">
        <a class="forma-site-header__brand" href="#top"><span class="forma-site-header__mark" aria-hidden="true">EX</span><span class="forma-site-header__name">Example / Product</span></a>
        <p class="forma-site-header__tagline">Evidence-driven engineering systems</p>
      </div>
      <nav class="forma-site-nav" aria-label="Primary">
        <ul class="forma-site-nav__list">
          <li><a class="forma-site-nav__link" href="#top" aria-current="page">Overview</a></li>
          <li><a class="forma-site-nav__link" href="#research">Research</a></li>
          <li><a class="forma-site-nav__link" href="#docs">Documentation</a></li>
          <li><a class="forma-site-nav__link" data-forma-variant="action" href="#contact">Get in touch</a></li>
        </ul>
      </nav>
    </div>
  </header>
</div>
</forma-site-header>

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

Examples

Scenario

Current section on a subpage

On a documentation subpage the Documentation link is marked aria-current="true" (the current section, not the exact page). It gets the same persistent under-rule as aria-current="page". No action link is used here, so no destination competes with the page content.

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

Harbor / Limen

Behavior at the interface boundary

HTML · Current section on a subpage Raw HTML for HTML · Current section on a subpage
<forma-site-header class="forma-component-tag">
  <div class="forma-site">
    <header class="forma-site-header">
      <div class="forma-site-header__inner">
        <div class="forma-site-header__identity">
          <a class="forma-site-header__brand" href="#site-header-current-section-home"><span class="forma-site-header__mark" aria-hidden="true">LM</span><span class="forma-site-header__name">Harbor / Limen</span></a>
          <p class="forma-site-header__tagline">Behavior at the interface boundary</p>
        </div>
        <nav class="forma-site-nav" aria-label="Limen">
          <ul class="forma-site-nav__list">
            <li><a class="forma-site-nav__link" id="site-header-current-section-home" href="#site-header-current-section-home">Overview</a></li>
            <li><a class="forma-site-nav__link" href="#site-header-current-section-home" aria-current="true">Documentation</a></li>
            <li><a class="forma-site-nav__link" href="#site-header-current-section-home">Releases</a></li>
          </ul>
        </nav>
      </div>
    </header>
  </div>
</forma-site-header>

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

Scenario

Long brand name without tagline

A long compound product name and no tagline. The name wraps inside the identity group rather than truncating, and the navigation drops below the identity when both no longer fit on one row.

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

HTML · Long brand name without tagline Raw HTML for HTML · Long brand name without tagline
<forma-site-header class="forma-component-tag">
  <div class="forma-site">
    <header class="forma-site-header">
      <div class="forma-site-header__inner">
        <div class="forma-site-header__identity">
          <a class="forma-site-header__brand" href="#site-header-long-brand-name-top"><span class="forma-site-header__mark" aria-hidden="true">TR</span><span class="forma-site-header__name">Example Harbor / Tutoris Research Publications</span></a>
        </div>
        <nav class="forma-site-nav" aria-label="Tutoris">
          <ul class="forma-site-nav__list">
            <li><a class="forma-site-nav__link" id="site-header-long-brand-name-top" href="#site-header-long-brand-name-top" aria-current="page">Publications</a></li>
            <li><a class="forma-site-nav__link" href="#site-header-long-brand-name-top">Methods</a></li>
            <li><a class="forma-site-nav__link" href="#site-header-long-brand-name-top">Datasets</a></li>
            <li><a class="forma-site-nav__link" href="#site-header-long-brand-name-top">About</a></li>
            <li><a class="forma-site-nav__link" data-forma-variant="action" href="#site-header-long-brand-name-top">Subscribe</a></li>
          </ul>
        </nav>
      </div>
    </header>
  </div>
</forma-site-header>

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 navigation wraps

Five destinations at phone width. The tagline yields, the brand stays on its own row, and the links wrap into two right-aligned rows that each keep a 44px target.

Live demo. 6 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 56rem header width the tagline is hidden (a container query on the header), keeping navigation to about two lines.
  • The navigation list wraps and stays right-aligned; no destination is hidden behind a menu button.
  • Each link, the action link and the brand are at least 44px tall; links are padded horizontally so short labels stay comfortable to tap.
  • The header is not sticky below 40rem width or 36rem height, so it scrolls away instead of permanently consuming screen space in either orientation.
HTML · Phone navigation wraps Raw HTML for HTML · Phone navigation wraps
<forma-site-header class="forma-component-tag">
  <div class="forma-site">
    <header class="forma-site-header">
      <div class="forma-site-header__inner">
        <div class="forma-site-header__identity">
          <a class="forma-site-header__brand" href="#site-header-mobile-wrapping-nav-top"><span class="forma-site-header__mark" aria-hidden="true">EH</span><span class="forma-site-header__name">Example Harbor</span></a>
          <p class="forma-site-header__tagline">Evidence-driven engineering systems</p>
        </div>
        <nav class="forma-site-nav" aria-label="Example Harbor">
          <ul class="forma-site-nav__list">
            <li><a class="forma-site-nav__link" id="site-header-mobile-wrapping-nav-top" href="#site-header-mobile-wrapping-nav-top" aria-current="page">Overview</a></li>
            <li><a class="forma-site-nav__link" href="#site-header-mobile-wrapping-nav-top">Research</a></li>
            <li><a class="forma-site-nav__link" href="#site-header-mobile-wrapping-nav-top">Products</a></li>
            <li><a class="forma-site-nav__link" href="#site-header-mobile-wrapping-nav-top">Writing</a></li>
            <li><a class="forma-site-nav__link" data-forma-variant="action" href="#site-header-mobile-wrapping-nav-top">Get in touch</a></li>
          </ul>
        </nav>
      </div>
    </header>
  </div>
</forma-site-header>

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-site-navstring—Names the navigation landmark. Use "Primary" and give any other nav on the page a different name.
aria-currenta.forma-site-nav__linkpage | trueabsentpage for the exact current page, true for the current section on a subpage. Mark only one link.
aria-hiddenspan.forma-site-header__marktrue—Required. The mark is decorative; the visible name is the brand link's accessible name.
hrefaURL—Ordinary navigation links; the site owns routing.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-site-headerBlock class—Banner root. Draws the bottom rule and a translucent, blurred page background, and is the forma-site-header size container. Sticky at 40rem wide and 36rem tall or more.
.forma-site-header__brandElement class—Brand link with a 44px minimum height; underlines on hover.
.forma-site-header__identityElement class—Groups the brand link and optional tagline; wraps internally.
.forma-site-header__innerElement class—Wrapping flex row, capped at the maximum layout width with fluid gutters, that places identity and navigation at opposite ends.
.forma-site-header__markElement class—Square decorative mark on the inverse surface. Always aria-hidden="true".
.forma-site-header__nameElement class—Visible brand name. Wraps anywhere rather than truncating and never hides.
.forma-site-header__taglineElement class—Optional supplementary line in the mono label size. Hidden when the header is narrower than 56rem.
.forma-site-navBlock class—The navigation landmark element.
.forma-site-nav__linkElement class—Navigation link: 44px minimum height, no underline, and a transparent bottom rule that shows on hover and when current.
.forma-site-nav__listElement class—Unstyled list that wraps its links and aligns them to the inline end.
[aria-current]Attribute hook"page", "true"page or true on a navigation link draws a persistent strong under-rule (Highlight in forced colors).
[data-forma-variant]Attribute hook"action"action on at most one navigation link renders it with the tone's action background and text colors, as the site's main conversion.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the brand link and navigation links in source order.
EnterFollows the focused link (native link behavior).

States

Site header states
StateHow it is expressedPresentation
Defaultno attributesLink text in the tone's text color with a transparent under-rule.
Hover:hoverThe under-rule turns the accent color; the brand link underlines; the action link shifts to the action hover background.
Currentaria-current="page" or "true"A persistent strong under-rule marks the current destination.
Focus:focus-visibleThe shell's outline and halo ring surround the focused link.
Actiondata-forma-variant="action"Filled link that reads as the primary conversion; bordered in forced colors.
Sticky@media (min-width: 40rem) and (min-height: 36rem)The header sticks to the top of the viewport; anchor targets get scroll padding below it.

Accessibility

Forma provides

  • Keeps navigation as a native nav with a list of anchors; nothing is hidden at narrow widths.
  • Provides 44px minimum targets on the brand and every navigation link.
  • Marks the current destination with a persistent rule in addition to aria-current, and uses Highlight for it in forced colors.
  • Disables sticky positioning on short or narrow viewports so the header cannot obscure focused content (WCAG 2.4.11).
  • Keeps the brand name visible and readable at every width.

Your application supplies

  • Set aria-current on exactly one link and keep it accurate for the rendered page.
  • Mark the decorative mark aria-hidden="true" and give the brand link a meaningful visible name.
  • Label the primary navigation and give other navigation landmarks distinct labels.
  • Use data-forma-variant="action" on at most one link.

Responsive behavior

  • The inner row is a wrapping flex container: navigation moves below the identity when both do not fit.
  • The navigation list wraps onto additional lines and stays aligned to the inline end.
  • A container query hides the tagline below a 56rem header width; the brand name wraps with overflow-wrap: anywhere and never hides.
  • Sticky positioning applies only at min-width: 40rem and min-height: 36rem.

Motion

  • No animation: hover and current states change the under-rule and colors instantly.
  • Reduced-motion users see the same result, because the shell removes all transitions inside .forma-site.

Usage guidance

Do

  • Keep primary navigation to a handful of destinations with short, specific labels.
  • Reserve the action variant for the one conversion most visitors should take.

Avoid

  • Replacing the wrapping list with a script-driven hamburger menu.
  • Removing the brand name and relying on the mark alone.
  • Signalling the current page with color only.

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.