Text roles are typographic treatments for text that frames other content. They change size, family, case and color only; the element you put them on keeps its own meaning. Three belong to the marketing layer and are used inside a MarketingShell (.forma-site): the eyebrow (a small uppercase label above a heading), the lead (the larger introductory paragraph under a heading) and the statement (a display-size pull statement with an accent rule). The fourth, the component kicker, belongs to the application layer: a small monospaced uppercase label that names the kind of panel or workflow above its heading.
Use when
A marketing or documentation section needs a category label above its heading: forma-eyebrow.
The first paragraph of a section summarizes it and should read first: forma-lead.
One sentence of a page deserves display-size emphasis as a pull statement: forma-statement.
An application panel needs a small label naming its kind or context above the heading: forma-component-kicker.
Avoid when
Headings: use real h1-h6 elements; an eyebrow or kicker is never the heading.
Roles never add semantics: an eyebrow is a p, a statement is whatever element you choose (often blockquote), a kicker is a p or span.
Eyebrow, lead and statement read marketing role tokens (--forma-type-size-*, --forma-tone-*), so they follow the surface tone they sit on.
Lead and statement sizes are fluid clamp() values that grow with viewport width.
The component kicker uses core semantic tokens and needs no marketing shell.
Basic example
The smallest correct markup: the canonical pattern from patterns/text-roles.html inside its public tag. Copy this first, then adapt labels, names and state.
Canonical
Minimal text roles
Rendered from the canonical pattern file.
Release 0.3
Faster onboarding for new teams
A lead paragraph introduces the section in one or two sentences.
Forma keeps behavior in the application and presentation in the design system.
<forma-text-roles class="forma-component-tag">
<div class="forma-site">
<p class="forma-eyebrow">Release 0.3</p>
<h2>Faster onboarding for new teams</h2>
<p class="forma-lead">A lead paragraph introduces the section in one or two sentences.</p>
<blockquote class="forma-statement"><p>Forma keeps behavior in the application and presentation in the design system.</p></blockquote>
<span class="forma-component-kicker">Component kicker</span>
</div>
</forma-text-roles>
Click or tap the code once to select all of it, then copy.
Examples
Scenario
Section introduction
An eyebrow names the section's category, the h2 states the point and a lead paragraph summarizes it. Reading order is eyebrow, heading, lead; the heading remains the section's accessible name.
Security
Evidence you can hand to an auditor
Every release records who approved it, which checks ran and what changed, so compliance reviews take hours instead of weeks.
<forma-text-roles class="forma-component-tag">
<div class="forma-site">
<section class="forma-section" aria-labelledby="text-roles-section-introduction-title">
<p class="forma-eyebrow">Security</p>
<h2 id="text-roles-section-introduction-title">Evidence you can hand to an auditor</h2>
<p class="forma-lead">Every release records who approved it, which checks ran and what changed, so compliance reviews take hours instead of weeks.</p>
</section>
</div>
</forma-text-roles>
Click or tap the code once to select all of it, then copy.
Scenario
Pull statement in an article
A statement set between ordinary paragraphs. It is a blockquote because it repeats a line from the article; the accent rule above it and the display face set it apart without a new heading level.
Why we moved validation to the edge
Most of our support tickets came from forms that accepted values the back office later rejected. Moving the same rules into the page removed the delay between a mistake and its explanation.
A rule that fails late is a rule the user never learns.
The rules still run on the server; the page only reports them sooner.
<forma-text-roles class="forma-component-tag">
<div class="forma-site">
<article aria-labelledby="text-roles-pull-statement-title">
<h2 id="text-roles-pull-statement-title">Why we moved validation to the edge</h2>
<p>Most of our support tickets came from forms that accepted values the back office later rejected. Moving the same rules into the page removed the delay between a mistake and its explanation.</p>
<blockquote class="forma-statement"><p>A rule that fails late is a rule the user never learns.</p></blockquote>
<p>The rules still run on the server; the page only reports them sooner.</p>
</article>
</div>
</forma-text-roles>
Click or tap the code once to select all of it, then copy.
Scenario
Kicker on an application panel
In an application layout the component kicker names the kind of panel above its heading. It works without the marketing shell and does not replace the heading.
Change review
Rotate the payments signing key
Scheduled for Friday 18:00 UTC. Two approvals are recorded and one is still required.
<forma-text-roles class="forma-component-tag">
<section class="forma-stack" data-density="compact" aria-labelledby="text-roles-application-kicker-title">
<p class="forma-component-kicker">Change review</p>
<h2 id="text-roles-application-kicker-title">Rotate the payments signing key</h2>
<p>Scheduled for Friday 18:00 UTC. Two approvals are recorded and one is still required.</p>
</section>
</forma-text-roles>
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
Hero introduction on a phone
Eyebrow, heading and lead at phone width. The lead's fluid size steps down toward its 1.125rem minimum and wraps within the column.
Frames narrower than the selected width show the component at the width available.
What changes at narrow widths
The lead uses clamp(1.125rem, 0.875rem + 0.85vw, 1.5rem), so it is smallest on phones and still larger than body text.
The lead's 62ch measure limit never applies at phone width; the text simply fills the column and wraps.
Eyebrow text is uppercase and letter-spaced; keep it to one or two words so it does not wrap awkwardly at 320px.
Nothing overflows horizontally; statements also use a fluid size (1.5rem minimum) and wrap.
<forma-text-roles class="forma-component-tag">
<div class="forma-site">
<section class="forma-section" aria-labelledby="text-roles-mobile-hero-introduction-title">
<p class="forma-eyebrow">Field service</p>
<h2 id="text-roles-mobile-hero-introduction-title">Every visit, planned before the van leaves</h2>
<p class="forma-lead">Technicians see parts, access notes and the customer's history on one screen, even without a signal.</p>
</section>
</div>
</forma-text-roles>
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.
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 / article
id of the heading
—
Names the region by its heading, not by the eyebrow or kicker.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-eyebrow
Block class
—
Marketing layer. Small (--forma-type-size-label) uppercase monospaced label in --forma-tone-label, with label weight and tracking and a bottom margin. Use inside .forma-site.
.forma-lead
Block class
—
Marketing layer. Introductory paragraph at --forma-type-size-lead (fluid, 1.125-1.5rem) with lead line height, limited to the narrow measure (62ch), in --forma-tone-text.
.forma-statement
Block class
—
Marketing layer. Display-face pull statement at --forma-type-size-statement (fluid, 1.5-2.4rem) with an accent rule above; nested paragraphs inherit its color and drop the measure limit.
.forma-component-kicker
Block class
—
Application layer. 0.6875rem monospaced uppercase label with 0.08em tracking in the secondary accent color.
Keyboard interaction
Keys
Result
None
Text roles are not interactive and add no keyboard behavior.