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.
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.
<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.
<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.
<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.
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.
<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.
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
.forma-callout
id 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__label
string
—
Referenced by the callout's aria-labelledby.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-callout
Block class
—
Root (aside, or figure for evidence). Bordered block with an accent-width inline-start rule, kept to the reading measure.
.forma-callout__label
Element 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-rule
Custom property
default 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
Keys
Result
—
Not interactive. Links inside follow native link behavior.
States
Callout states
State
How it is expressed
Presentation
Note
data-forma-callout="note" or absent
Solid inline-start rule on a hairline frame.
Caution
data-forma-callout="caution"
Heavy block-start rule and full-strength frame.
Evidence
data-forma-callout="evidence" on a figure
Dashed frame with a solid inline-start rule; the quotation reads as body text with a muted source caption.
Decision
data-forma-callout="decision"
Double inline-start rule at twice the accent width.
Forced colors and print
@media (forced-colors: active), print
Borders 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.