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.
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.
<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.
<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.
<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.
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.
<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.
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
Attribute
On
Values
Default
Description
aria-labelledby
section.forma-hero
id of the hero title
—
Names the hero region by its title so it is exposed as a labelled region.
id
.forma-hero__title
string
—
Referenced by the section's aria-labelledby.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-hero
Block class
—
Region root: a wrapping flex row with large top padding and a strong bottom rule. Requires an .forma-site ancestor.
.forma-hero__aside
Element class
—
Optional supporting region (statement, facts). Flexes around 18 to 30rem and wraps below the content when space runs out.
.forma-hero__content
Element 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__title
Element class
—
Spacing for the page title. Its size comes from the heading level; directly after an eyebrow its top margin is removed.
Keyboard interaction
Keys
Result
Tab / Shift+Tab
Moves through the hero's links and buttons in source order: content actions before anything in the aside.
States
Hero states
State
How it is expressed
Presentation
Side by side
enough inline space
Content and aside share one row, aligned to their bottom edges.
Stacked
flex-wrap when space runs out
The aside moves below the content in source order.
Without aside
omit .forma-hero__aside
Content 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.