Site and editorial

Callout

<forma-callout>

Labelled note, caution, evidence, or decision inside prose; a visible label and rule pattern carry the kind without relying on color.

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

Purpose

A callout marks supporting material inside long-form content that a reader must notice: a note, a caution, cited evidence or a recorded decision. Each callout starts with a visible .forma-callout__label naming its kind and is named by that label through aria-labelledby. data-forma-callout selects the kind; each kind has its own rule pattern (solid, heavy frame, dashed, double) so kinds stay distinct in grayscale, forced colors and print. Notes, cautions and decisions are aside elements; evidence is a figure holding a blockquote and a figcaption. Callouts have no state and no runtime.

Use when

  • A reader could skip useful context and should see it is optional (note).
  • A consequence must be weighed before acting on the surrounding text (caution).
  • Quoting or citing source material with its source (evidence).
  • Recording a settled outcome that later sections refer to (decision).

Avoid when

  • Ordinary emphasis, decoration or a pull quote: use strong, a plain blockquote or a heading in Prose.
  • Reporting live application status, errors or success: use Alert or Validation message.
  • Asking the reader to act on the whole page: use a Call to action.

Behavior to know

  • The visible label is the primary cue; the rule pattern is the second, non-color cue; color is only a third.
  • Note (or no data-forma-callout) is a solid accent-width inline-start rule; caution adds a heavy block-start rule and a strong frame; evidence has a dashed frame; decision has a double inline-start rule.
  • Callouts keep the reading measure and read in source order; nothing is floated or moved.

Basic example

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

Canonical

Minimal callout

Rendered from the canonical pattern file.

Callouts mark supporting material, not ordinary emphasis

Most prose needs no callout. Use one only when a reader must notice a note, a caution, cited evidence, or a recorded decision.

Evidence

Quoted or cited source material stays a quotation in the document outline.

Source: the measurement it came from
HTML · Minimal callout Raw HTML for HTML · Minimal callout
<forma-callout class="forma-component-tag">
<div class="forma-site">
  <article class="forma-prose">
    <h2>Callouts mark supporting material, not ordinary emphasis</h2>
    <p>Most prose needs no callout. Use one only when a reader must notice a note, a caution, cited evidence, or a recorded decision.</p>
    <aside class="forma-callout" data-forma-callout="note" aria-labelledby="callout-note">
      <p class="forma-callout__label" id="callout-note">Note</p>
      <p>Supporting context that a reader can skip without losing the argument.</p>
    </aside>
    <aside class="forma-callout" data-forma-callout="caution" aria-labelledby="callout-caution">
      <p class="forma-callout__label" id="callout-caution">Caution</p>
      <p>A consequence the reader must weigh before acting on the surrounding text.</p>
    </aside>
    <figure class="forma-callout" data-forma-callout="evidence" aria-labelledby="callout-evidence">
      <p class="forma-callout__label" id="callout-evidence">Evidence</p>
      <blockquote><p>Quoted or cited source material stays a quotation in the document outline.</p></blockquote>
      <figcaption>Source: the measurement it came from</figcaption>
    </figure>
    <aside class="forma-callout" data-forma-callout="decision" aria-labelledby="callout-decision">
      <p class="forma-callout__label" id="callout-decision">Decision</p>
      <p>The outcome that was settled, stated once so later sections can refer to it.</p>
    </aside>
  </article>
</div>
</forma-callout>

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

Examples

Scenario

Caution before an upgrade step

An upgrade guide where one step has a consequence. The caution sits directly after the paragraph it qualifies, with a list inside.

Upgrade to 0.4.0

Edit forma.lock to the new version, then run the installer with --update.

Commit the lock and any markup changes as one reviewable change.

HTML · Caution before an upgrade step Raw HTML for HTML · Caution before an upgrade step
<forma-callout class="forma-component-tag">
  <div class="forma-site">
    <article class="forma-prose">
      <h3>Upgrade to 0.4.0</h3>
      <p>Edit <code>forma.lock</code> to the new version, then run the installer with <code>--update</code>.</p>
      <aside class="forma-callout" data-forma-callout="caution" aria-labelledby="callout-caution-before-upgrade-label">
        <p class="forma-callout__label" id="callout-caution-before-upgrade-label">Caution</p>
        <p>This release renames two classes. Before deploying:</p>
        <ul><li>search the site for the old class names;</li><li>run the local-CSS policy check.</li></ul>
      </aside>
      <p>Commit the lock and any markup changes as one reviewable change.</p>
    </article>
  </div>
</forma-callout>

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

Scenario

Evidence followed by a decision

A design record: measured evidence as a figure with its source, then the decision it supports. Later sections can refer to the decision by its label.

Why the header is not sticky on phones

Evidence

At 390 by 844 pixels a sticky two-line header covered 14% of the viewport and hid focused links in 3 of 12 keyboard sweeps.

Source: focus-sweep test, September 2026
HTML · Evidence followed by a decision Raw HTML for HTML · Evidence followed by a decision
<forma-callout class="forma-component-tag">
  <div class="forma-site">
    <article class="forma-prose">
      <h3>Why the header is not sticky on phones</h3>
      <figure class="forma-callout" data-forma-callout="evidence" aria-labelledby="callout-evidence-and-decision-evidence">
        <p class="forma-callout__label" id="callout-evidence-and-decision-evidence">Evidence</p>
        <blockquote><p>At 390 by 844 pixels a sticky two-line header covered 14% of the viewport and hid focused links in 3 of 12 keyboard sweeps.</p></blockquote>
        <figcaption>Source: focus-sweep test, September 2026</figcaption>
      </figure>
      <aside class="forma-callout" data-forma-callout="decision" aria-labelledby="callout-evidence-and-decision-decision">
        <p class="forma-callout__label" id="callout-evidence-and-decision-decision">Decision</p>
        <p>The header sticks only at 40rem wide and 36rem tall or more.</p>
      </aside>
    </article>
  </div>
</forma-callout>

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 note in an article

A note inside an article at phone width, containing a long inline code value.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • The callout is capped at the reading measure and shrinks to the column; its padding stays compact so text keeps most of the width.
  • Text inside wraps; long inline code values break anywhere rather than widening the page.
  • There are no interactive targets of its own; links inside keep the shell's underline and focus ring.
  • There are no fixed heights, so 200% text and text-spacing overrides grow the callout instead of clipping it.
HTML · Phone note in an article Raw HTML for HTML · Phone note in an article
<forma-callout class="forma-component-tag">
  <div class="forma-site">
    <article class="forma-prose">
      <p>Sites load the theme's webfonts themselves.</p>
      <aside class="forma-callout" data-forma-callout="note" aria-labelledby="callout-mobile-note-label">
        <p class="forma-callout__label" id="callout-mobile-note-label">Note</p>
        <p>Fallback stacks are defined, so pages stay readable if <code>fonts.example.com/css2?family=Example+Mono</code> fails to load.</p>
      </aside>
    </article>
  </div>
</forma-callout>

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-labelledby.forma-calloutid of .forma-callout__label—Required. Names the aside or figure by its visible label, so it is announced as, for example, a "Caution" complementary region.
id.forma-callout__labelstring—Referenced by the callout's aria-labelledby.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-calloutBlock class—Root (aside, or figure for evidence). Bordered block with an accent-width inline-start rule, kept to the reading measure.
.forma-callout__labelElement class—Visible kind label in mono uppercase label type. Always the first child.
[data-forma-callout]Attribute hook"caution", "decision", "evidence"Kind: note (default styling), caution (heavy block-start rule and strong frame), evidence (dashed frame) or decision (double inline-start rule).
--forma-callout-ruleCustom propertydefault var(--forma-tone-rule-strong)Color of the inline-start rule. Defaults to the tone's strong rule; caution uses the warning status color, evidence the info status color and decision the primary accent.
Keyboard interaction
KeysResult
—Not interactive. Links inside follow native link behavior.

States

Callout states
StateHow it is expressedPresentation
Notedata-forma-callout="note" or absentSolid inline-start rule on a hairline frame.
Cautiondata-forma-callout="caution"Heavy block-start rule and full-strength frame.
Evidencedata-forma-callout="evidence" on a figureDashed frame with a solid inline-start rule; the quotation reads as body text with a muted source caption.
Decisiondata-forma-callout="decision"Double inline-start rule at twice the accent width.
Forced colors and print@media (forced-colors: active), printBorders become CanvasText; in print the callout is not split across pages.

Accessibility

Forma provides

  • Distinguishes kinds by visible label and rule pattern, not color alone.
  • Keeps text at primary contrast on every tone and the label at the validated label color.
  • Keeps the frame visible in forced colors and print and avoids page breaks inside a callout.

Your application supplies

  • Start every callout with a visible label and reference it with aria-labelledby.
  • Use aside for note, caution and decision, and figure with blockquote and figcaption for evidence.
  • Place the callout next to the text it qualifies and keep callouts rare.

Responsive behavior

  • Capped at --forma-layout-measure; shrinks with its column. No breakpoints.
  • Content wraps; there are no fixed heights.

Motion

  • No animation: callouts are static and declare no transitions or animations, with or without reduced motion.

Usage guidance

Do

  • Choose the kind by what the reader must do with it: skip, weigh, verify or refer back.
  • Cite a source in every evidence callout.

Avoid

  • Using a caution for ordinary emphasis; it loses force.
  • Nesting callouts or placing a callout inside another component.

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.