Figure

Self-contained content with an optional caption. Images, code, diagrams, quotes.

The <figure> element wraps self-contained content — typically an image, diagram, code block, or data visualisation — that is referenced from the main flow but could be moved without breaking the reading order. ASW resets the browser's default indented margin and styles the optional <figcaption> as muted small text beneath the content.

Image with caption

Wrap an <img> in <figure> and add a <figcaption> to label it. The caption appears directly below the image in muted small text. No classes required.

<figure>
  <img src="/path/to/image.png" alt="Descriptive alt text">
  <figcaption>Figure 1 — System architecture overview.</figcaption>
</figure>

Live demo

Agent HTML Browser Agent → HTML → Browser
Figure 1 — The ASW pipeline. Agents generate semantic HTML; the browser renders it with agentic.css.

Code figure

A <figure> wrapping a <pre><code> block lets you caption a code example — useful for listing numbers, file names, or source references.

<figure>
  <pre><code>select * from notes where tag = 'daily';</code></pre>
  <figcaption>Listing 1 — Query to fetch all daily notes.</figcaption>
</figure>

Live demo

select id, title, created_at
from notes
where tag = 'daily'
order by created_at desc;
Listing 1 — Query to fetch all daily notes, newest first.

Without caption

<figcaption> is optional. Use a bare <figure> to group self-contained content without labelling it — the margin reset still applies, keeping spacing consistent.

<figure>
  <img src="/chart.png" alt="Bar chart showing weekly session counts">
</figure>

Include an alt attribute on every <img> even when there is no <figcaption>. The caption supplements the alt text; it does not replace it.

Design tokens

Figure layout is controlled by two spacing decisions in ASW:

Property Value Effect
figure margin 0 0 var(--asw-space-4) Removes browser indentation; adds bottom spacing
figcaption padding calc(var(--asw-space-4) * 0.5) 0 Vertical breathing room between content and caption
figcaption color var(--asw-text-muted) Subdued tone to distinguish caption from body copy
figcaption font-size var(--asw-text-sm) Slightly smaller than body text

Accessibility

  • Always provide alt text for <img> elements. Decorative images use alt="".
  • <figcaption> is programmatically associated with its parent <figure>. Assistive technology announces the caption as part of the figure's accessible description.
  • If the figure contains a complex diagram, consider supplementing alt with a longer prose description in the surrounding text or in an aria-describedby target.
  • Avoid using <figure> as a generic wrapper for layout purposes. Reserve it for genuinely self-contained, referenceable content.