Site and editorial

Prose

<forma-prose>

Long-form content constrained to the reading measure with underlined links and consistent heading rhythm.

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

Purpose

Prose is the container for long-form writing on marketing and documentation pages: articles, guides and release notes rendered from Markdown or written by hand. .forma-prose caps the region at the reading measure, spaces its direct headings, reduces h2 to the statement size so section headings do not compete with the page title, and keeps paragraphs and list items at primary text contrast. Plain HTML inside inherits the .forma-site foundations: underlined links, inline code, blockquotes and rules.

Use when

  • Rendering an article, guide or policy page made of headings, paragraphs and lists.
  • Markdown output needs Forma styling without adding classes to each element.
  • The article column of a Documentation layout.

Avoid when

  • Short marketing sections with a heading and a sentence: use Section heading and components.
  • Application help text or form descriptions: use the application patterns, which are not scoped to .forma-site.
  • Constraining line length in application UI: use Measure.

Behavior to know

  • Maximum width is --forma-layout-measure; lists and paragraphs share it.
  • Direct h1, h2 and h3 children get fixed rhythm; a heading that is the first child has no top margin.
  • Direct figures, code samples and pre elements get block margins.
  • Links are underlined and thicken on hover; in print, external links show their URL after the text.

Basic example

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

Canonical

Minimal prose

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.

Long-form content stays inside the reading measure

Prose regions keep line length readable, preserve underlined links such as the measure contract, and give headings consistent rhythm.

Supporting detail

  • Lists inherit the same measure.
  • Inline code stays legible.

Quotations use the display face without a second emphasis channel.

HTML · Minimal prose Raw HTML for HTML · Minimal prose
<forma-prose class="forma-component-tag">
<div class="forma-site">
  <article class="forma-prose">
    <h2>Long-form content stays inside the reading measure</h2>
    <p>Prose regions keep line length readable, preserve underlined links such as <a href="#measure">the measure contract</a>, and give headings consistent rhythm.</p>
    <h3>Supporting detail</h3>
    <ul><li>Lists inherit the same measure.</li><li>Inline <code>code</code> stays legible.</li></ul>
    <blockquote><p>Quotations use the display face without a second emphasis channel.</p></blockquote>
  </article>
</div>
</forma-prose>

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

Examples

Scenario

Guide with a code sample and callout

A short guide composing a Code sample and a Callout inside prose. The figure takes the prose block margins and the callout keeps the measure.

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

Pin a release

Record the version and checksum of every asset in forma.lock, then install exactly what it pins.

Install what the lock pins
bash install.sh

Upgrading

Change the version, run bash install.sh --update, and review the release notes.

HTML · Guide with a code sample and callout Raw HTML for HTML · Guide with a code sample and callout
<forma-prose class="forma-component-tag">
  <div class="forma-site">
    <article class="forma-prose">
      <h2>Pin a release</h2>
      <p>Record the version and checksum of every asset in <code>forma.lock</code>, then install exactly what it pins.</p>
      <figure class="forma-code-figure">
        <figcaption id="prose-guide-with-code-caption">Install what the lock pins</figcaption>
        <pre class="forma-code" tabindex="0" aria-labelledby="prose-guide-with-code-caption"><code>bash install.sh</code></pre>
      </figure>
      <aside class="forma-callout" data-forma-callout="note" aria-labelledby="prose-guide-with-code-note">
        <p class="forma-callout__label" id="prose-guide-with-code-note">Note</p>
        <p>The installer needs only bash, curl and a sha256 tool.</p>
      </aside>
      <h3>Upgrading</h3>
      <p>Change the version, run <code>bash install.sh --update</code>, and review <a href="#prose-guide-with-code-caption">the release notes</a>.</p>
    </article>
  </div>
</forma-prose>

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

Scenario

Release notes with nested lists

Markdown-style release notes: headings, a nested list, strong text and a horizontal rule. No element carries a class.

0.3.0

Breaking: the landing layout is removed.

Added

  • Callout, with four kinds:
    • note and caution;
    • evidence and decision.
  • Documentation layout that regroups by main-region width.

Fixed

  1. Header no longer sticks on short viewports.
  2. Card focus ring is drawn inside the card edge.
HTML · Release notes with nested lists Raw HTML for HTML · Release notes with nested lists
<forma-prose class="forma-component-tag">
  <div class="forma-site">
    <article class="forma-prose">
      <h2>0.3.0</h2>
      <p><strong>Breaking:</strong> the landing layout is removed.</p>
      <h3>Added</h3>
      <ul>
        <li>Callout, with four kinds:
          <ul><li>note and caution;</li><li>evidence and decision.</li></ul>
        </li>
        <li>Documentation layout that regroups by main-region width.</li>
      </ul>
      <hr>
      <h3>Fixed</h3>
      <ol><li>Header no longer sticks on short viewports.</li><li>Card focus ring is drawn inside the card edge.</li></ol>
    </article>
  </div>
</forma-prose>

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 article with long inline code

An article at phone width with a quotation and a long inline code value.

Live demo. 1 native action works here and is 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 measure cap stops mattering on phones; the article takes the column width and text wraps normally.
  • Inline code breaks anywhere (overflow-wrap: anywhere), so long identifiers and paths do not widen the page.
  • Heading sizes are fluid and balance their line breaks; the statement-sized h2 stays below the page title.
  • Inline links are only as large as their text, so write them as whole phrases to give touch users a usable target; they keep their underline and the shell's focus ring.
HTML · Phone article with long inline code Raw HTML for HTML · Phone article with long inline code
<forma-prose class="forma-component-tag">
  <div class="forma-site">
    <article class="forma-prose">
      <h2>Why tones, not colors</h2>
      <p>On the surface tone, links and labels read <code>var(--forma-color-text-on-secondary-surface)</code> instead of the accent, so a region can change its background without restyling what is inside.</p>
      <blockquote><p>Links on the secondary surface fall back to primary text, because the accent is below 4.5:1 there.</p></blockquote>
      <p>See <a href="#prose-mobile-article-end">the token contract</a> for every validated pair.</p>
      <p id="prose-mobile-article-end">Tones are presentation only.</p>
    </article>
  </div>
</forma-prose>

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.

CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-proseBlock class—Long-form container. Caps width at the reading measure, redefines --forma-type-size-h2 to the statement size, spaces direct headings, keeps paragraph and list text at primary color, and gives direct figures and code blocks block margins.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through links and focusable code blocks in source order.

States

Prose states
StateHow it is expressedPresentation
Defaultno attributesMeasure-capped article on the surrounding tone.
Link hover:hover on aThe underline thickens; link color changes to the tone's hover link color.
Print@media printExternal links (href starting with http) print their URL after the link text.

Accessibility

Forma provides

  • Keeps links underlined, so they are identifiable without color.
  • Keeps paragraph and list text at primary contrast on every tone.
  • Uses rem and fluid sizes so 200% text and text-spacing overrides reflow without horizontal scrolling.

Your application supplies

  • Use a correct heading hierarchy with no skipped levels.
  • Write descriptive link text.
  • Mark up quotations, code and lists with their native elements.

Responsive behavior

  • Capped at --forma-layout-measure; below that it takes the column width. No breakpoints.
  • Inline code wraps anywhere; code blocks scroll inside themselves.
  • Images and media inside .forma-site are limited to 100% of their container.

Motion

  • No animation: link hover changes the underline thickness and color instantly.

Usage guidance

Do

  • Emit plain semantic HTML from Markdown and wrap it in .forma-prose.
  • Use Callout sparingly for material a reader must notice.

Avoid

  • Adding classes to individual paragraphs to restyle them.
  • Setting a wider max-width on the article; long lines reduce readability.

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.