Utilities

Text roles

<forma-text-roles>

Eyebrow, lead, statement and component kicker text roles that express hierarchy through type, not new semantics.

Authoring tag
<forma-text-roles>
Category
Utilities
Behavior owner
Native CSS
Canonical source
patterns/text-roles.html

Purpose

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.
  • Status or severity: use Status lozenge or Badge; text roles carry no state.
  • Quotations with a source that must be cited: use Callout with data-forma-callout="evidence".
  • Long-form body text: use Prose.

Behavior to know

  • 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.

Component kicker
HTML · Minimal text roles Raw HTML for HTML · Minimal text roles
<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.

HTML · Section introduction Raw HTML for HTML · Section introduction
<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.

HTML · Pull statement in an article Raw HTML for HTML · Pull statement in an article
<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.

HTML · Kicker on an application panel Raw HTML for HTML · Kicker on an application panel
<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.

Viewport width

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.
HTML · Hero introduction on a phone Raw HTML for HTML · Hero introduction on a phone
<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.

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 / articleid of the heading—Names the region by its heading, not by the eyebrow or kicker.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-eyebrowBlock 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-leadBlock 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-statementBlock 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-kickerBlock class—Application layer. 0.6875rem monospaced uppercase label with 0.08em tracking in the secondary accent color.
Keyboard interaction
KeysResult
NoneText roles are not interactive and add no keyboard behavior.

Form behavior

No form behavior.

States

Text roles states
StateHow it is expressedPresentation
Defaultclass on a text elementThe role's typography; no interactive states.
Surface toneancestor data-forma-tone (surface, elevated, inverse)Eyebrow, lead and statement read --forma-tone-*, so their colors stay legible on each marketing tone.
Forced colorsforced-colors: activeThe statement's accent rule becomes CanvasText; text uses system colors.

Accessibility

Forma provides

  • Changes presentation only; heading structure and element semantics are untouched.
  • Tone variables keep eyebrow, lead and statement colors at validated contrast on each marketing surface tone.
  • The statement's rule remains visible in forced colors.

Your application supplies

  • Keep a real heading after every eyebrow or kicker, and name regions by that heading.
  • Do not rely on the uppercase transform to convey anything; screen readers read the source text, so write it in normal case.
  • Use blockquote for a statement only when it repeats or quotes text; otherwise use a p.

Responsive behavior

  • Lead and statement sizes are fluid clamp() values tied to viewport width; eyebrow and kicker sizes are fixed.
  • The lead is limited to the 62ch narrow measure on wide screens and fills the column on narrow ones.
  • All roles wrap naturally and never cause horizontal overflow.

Motion

  • No animation: text roles are static typography.

Usage guidance

Do

  • Keep eyebrows and kickers to one to three words.
  • Use at most one statement per page section so it keeps its weight.

Avoid

  • Using an eyebrow as the only heading of a section.
  • Using marketing roles (eyebrow, lead, statement) inside application screens; use the component kicker there.
  • Styling long paragraphs as leads.

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.