Site and editorial

Hero

<forma-hero>

A page's first region: one promise, one primary action, and optional supporting context that stacks below it in source order.

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

Purpose

The hero is the first section inside the marketing shell's main region and carries the page's one primary recognition path: what this is, why it matters, and the action most visitors should take. .forma-hero__content holds the eyebrow, the page title (the page's only h1), a lead and actions; the optional .forma-hero__aside holds supporting context such as a statement, facts or badges. The two regions sit side by side when there is room and wrap into source order when there is not.

Use when

  • Opening a marketing, product or single-offer page with one clear promise.
  • The promise needs supporting proof (facts, a statement, release badges) that can follow it on narrow screens.
  • The page has one primary action that should be the first strong call to action.

Avoid when

  • Opening a documentation article: use Documentation layout with a prose heading.
  • Text must sit over photography or illustration: there is no scrim primitive yet (GAP-MKT-03), so text over imagery cannot be contrast-verified.
  • Introducing a later section of the page: use Section heading.

Behavior to know

  • Content takes the dominant share of the row (at least 55% when beside the aside); the aside flexes around 18 to 30rem.
  • No CSS reordering: the aside always follows the content for reading, focus and print.
  • A strong bottom rule closes the region; the regions align to their bottom edges when side by side.
  • The title size comes from the heading level inside .forma-site; .forma-hero__title only sets its spacing.

Basic example

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

Canonical

Minimal hero

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.

Applied research

State the promise before the proof

The hero carries one primary recognition path: what this is, why it matters, and the one action most visitors should take.

40%+ throughput
Delivery flow realigned
Hours to minutes
Reconciliation stabilized

Supporting context sits beside the promise on wide screens and below it on narrow ones, in source order.

HTML · Minimal hero Raw HTML for HTML · Minimal hero
<forma-hero class="forma-component-tag">
<div class="forma-site">
  <section class="forma-hero" aria-labelledby="hero-title">
    <div class="forma-hero__content">
      <p class="forma-eyebrow">Applied research</p>
      <h1 class="forma-hero__title" id="hero-title">State the promise before the proof</h1>
      <p class="forma-lead">The hero carries one primary recognition path: what this is, why it matters, and the one action most visitors should take.</p>
      <div class="forma-actions"><a class="forma-button" data-forma-variant="primary" href="#start">Book a working session</a><a class="forma-button" href="#work">See the body of work</a></div>
      <dl class="forma-facts">
        <div class="forma-facts__item"><dt>40%+ throughput</dt><dd>Delivery flow realigned</dd></div>
        <div class="forma-facts__item"><dt>Hours to minutes</dt><dd>Reconciliation stabilized</dd></div>
      </dl>
    </div>
    <div class="forma-hero__aside">
      <blockquote class="forma-statement"><p>Supporting context sits beside the promise on wide screens and below it on narrow ones, in source order.</p></blockquote>
    </div>
  </section>
</div>
</forma-hero>

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

Examples

Scenario

Product release hero

A product page hero with release badges and actions in the content region and facts in the aside. On a real page the title is the h1; the catalog page already has one, so this specimen uses h2.

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

Product / Quality evidence

Measure code health across every change

Each commit adds evidence instead of replacing the last snapshot.

  • Stable
  • Version 1.4.0

At a glance

Longitudinal
Evidence across commits
Deterministic
Same inputs, same report
HTML · Product release hero Raw HTML for HTML · Product release hero
<forma-hero class="forma-component-tag">
  <div class="forma-site">
    <section class="forma-hero" aria-labelledby="hero-product-release-title">
      <div class="forma-hero__content">
        <p class="forma-eyebrow">Product / Quality evidence</p>
        <h2 class="forma-hero__title" id="hero-product-release-title">Measure code health across every change</h2>
        <p class="forma-lead">Each commit adds evidence instead of replacing the last snapshot.</p>
        <ul class="forma-badge-list" aria-label="Release facts">
          <li><span class="forma-badge" data-forma-status="success">Stable</span></li>
          <li><span class="forma-badge">Version 1.4.0</span></li>
        </ul>
        <div class="forma-actions"><a class="forma-button" data-forma-variant="primary" href="#hero-product-release-title">Install</a><a class="forma-button" href="#hero-product-release-title">Read the documentation</a></div>
      </div>
      <div class="forma-hero__aside">
        <h3>At a glance</h3>
        <dl class="forma-facts">
          <div class="forma-facts__item"><dt>Longitudinal</dt><dd>Evidence across commits</dd></div>
          <div class="forma-facts__item"><dt>Deterministic</dt><dd>Same inputs, same report</dd></div>
        </dl>
      </div>
    </section>
  </div>
</forma-hero>

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

Scenario

Promise without supporting context

A single-offer hero with no aside: eyebrow, title and one primary action. Without an aside the content region takes the full width and the lead keeps its narrow reading measure.

Live demo. 1 native action works here and is verified by an outcome test.

Two-week diagnostic

Find the cause before you fund the fix

A fixed-scope engagement that ends with a defensible root cause and a treatment plan.

HTML · Promise without supporting context Raw HTML for HTML · Promise without supporting context
<forma-hero class="forma-component-tag">
  <div class="forma-site">
    <section class="forma-hero" aria-labelledby="hero-promise-only-title">
      <div class="forma-hero__content">
        <p class="forma-eyebrow">Two-week diagnostic</p>
        <h2 class="forma-hero__title" id="hero-promise-only-title">Find the cause before you fund the fix</h2>
        <p class="forma-lead">A fixed-scope engagement that ends with a defensible root cause and a treatment plan.</p>
        <div class="forma-actions"><a class="forma-button" data-forma-variant="primary" href="#hero-promise-only-title">Book a working session</a></div>
      </div>
    </section>
  </div>
</forma-hero>

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 hero with statement

At phone width the statement in the aside moves below the promise and actions, keeping source order.

Live demo. 2 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

  • The aside wraps below the content when the row cannot give the content at least 55% and the aside its minimum; there are no breakpoints.
  • Reading, focus and print order stay content first, aside second, because nothing is reordered with CSS.
  • Actions wrap onto separate lines and each button keeps a target of at least 44px.
  • The fluid title and statement sizes shrink with the viewport and headings balance their line breaks, so long titles do not overflow at 320px.
HTML · Phone hero with statement Raw HTML for HTML · Phone hero with statement
<forma-hero class="forma-component-tag">
  <div class="forma-site">
    <section class="forma-hero" aria-labelledby="hero-mobile-stacked-title">
      <div class="forma-hero__content">
        <p class="forma-eyebrow">Applied research</p>
        <h2 class="forma-hero__title" id="hero-mobile-stacked-title">State the promise before the proof</h2>
        <p class="forma-lead">What this is, why it matters, and the one action to take.</p>
        <div class="forma-actions"><a class="forma-button" data-forma-variant="primary" href="#hero-mobile-stacked-title">Book a working session</a><a class="forma-button" href="#hero-mobile-stacked-title">See the body of work</a></div>
      </div>
      <div class="forma-hero__aside">
        <blockquote class="forma-statement"><p>Observations stay separate from explanations until evidence removes the alternatives.</p></blockquote>
      </div>
    </section>
  </div>
</forma-hero>

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-labelledbysection.forma-heroid of the hero title—Names the hero region by its title so it is exposed as a labelled region.
id.forma-hero__titlestring—Referenced by the section's aria-labelledby.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-heroBlock class—Region root: a wrapping flex row with large top padding and a strong bottom rule. Requires an .forma-site ancestor.
.forma-hero__asideElement class—Optional supporting region (statement, facts). Flexes around 18 to 30rem and wraps below the content when space runs out.
.forma-hero__contentElement class—Dominant region for eyebrow, title, lead, badges and actions. Grows first and keeps at least 55% of the row while side by side.
.forma-hero__titleElement class—Spacing for the page title. Its size comes from the heading level; directly after an eyebrow its top margin is removed.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the hero's links and buttons in source order: content actions before anything in the aside.

States

Hero states
StateHow it is expressedPresentation
Side by sideenough inline spaceContent and aside share one row, aligned to their bottom edges.
Stackedflex-wrap when space runs outThe aside moves below the content in source order.
Without asideomit .forma-hero__asideContent spans the full width; the lead keeps its narrow measure.

Accessibility

Forma provides

  • Never reorders content and aside visually, so reading and focus order match the visual order at every width.
  • Uses rem and fluid type sizes with a rem term, so 200% text does not cause horizontal scrolling.
  • Buttons inside keep 44px targets and the shell's visible focus ring.

Your application supplies

  • Use the hero title as the page's single h1 and name the section with aria-labelledby.
  • Offer exactly one data-forma-variant="primary" action.
  • Put information required to act in the content region, not only in the aside.
  • Label lists of badges or facts, or precede them with a heading.

Responsive behavior

  • Content-driven recomposition with flex-wrap: no breakpoints.
  • The content keeps min(100%, 55%) of the row; the aside's basis is clamp(18rem, 32%, 30rem) with no minimum, so it never forces overflow.
  • Title, lead and statement use fluid sizes; the title's max-inline-size keeps lines short on wide screens.

Motion

  • No animation: the hero is static. Buttons inside interpolate color on hover only (removed under reduced motion).

Usage guidance

Do

  • Write the title as one promise in plain language, followed by one lead sentence.
  • Keep the aside to one kind of supporting evidence.

Avoid

  • Two primary actions, or a carousel of promises.
  • Placing text over imagery until a scrim-backed media variant exists.

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.