Figure & Caption Spacing

The figure is the canonical Verdigris composition for a visual with a caption. It covers three concrete cases on the web:

1. Canvas viz with caption. WaveformTrace, HarmonicSpectrum, ResolutionComparison, etc., framed by <CanvasFrame> with <figcaption> below.
2. Static image with caption. Hero photography, diagram screenshots, OEM-partner architecture diagrams.
3. ResourceCard chip. Image + title + body — the compact figure pattern used in card grids.

This guide unifies the three under one spacing spec so the figure register reads consistently across the site.

The pattern

┌──────────────────────────────┐
│                              │
│   <visual> -- legend, axis,  │  ← image / canvas / SVG
│   and series labels live     │     (the picture argues on its own)
│   INSIDE here                │
└──────────────────────────────┘
  Degrading rectifier caught 21 days early          ← <=7-word claim label (or none)

The claim label is optional. A figure that already argues at a glance ships with no visible caption at all. What the figure depicts (chart type, axes, series, sample rate, instrument) goes in the alt attribute, not in the caption.

All Verdigris web figures use this above-vs-below geometry: the visual sits above, the caption below. Tables are the only exception — table captions sit above the table (per categories/whitepapers/body.md, “tables read top-down so the caption belongs at the top”).

The caption is a claim, not a description

The picture is the argument. The caption is at most a <=7-word claim about the customer’s world, and a strong figure may carry none. See categories/composition/communicate-at-a-glance.md for the principle and the meta-language ban that governs every caption here.

Three hard rules follow from that:

1. A caption is a claim about the customer’s world, never a description of the artifact. “Degrading rectifier caught 21 days early” is a claim. “Three-phase load currents at 8 kHz” describes the chart. The first is a caption; the second is alt text.
2. Series, metric, and axis labels live INSIDE the visual, not in a prose legend below it. If a reader needs the caption to know which line is which, the legend is in the wrong place. Put it on the lines.
3. Artifact descriptions live in alt text. What the figure literally depicts (chart type, axes, series, instrument, sample rate) is accessibility metadata, not caption copy. The alt attribute carries it; the visible caption carries the claim.

The editorial figure-number register (a Fig. N label) is still permitted where numbering is genuinely needed (whitepapers, multi-figure case studies). On web marketing surfaces it is usually omitted: a claim label rarely needs a number.

Vertical rhythm spec

When an editorial figure-number register is genuinely used (whitepapers, multi-figure case studies), the optional Fig. N label and any second descriptive line keep the historical caption-strong / body-small (0.875rem / 14px / 400 Inter / 1.5) treatment with a 0.25rem (4px, spacing.1) title-to-body gap. On web marketing surfaces, prefer the single claim label or no caption.

Caption content rules

1. The caption is a <=7-word claim, not a title clause that names the chart. Degrading rectifier caught 21 days early is a caption. Three-phase load currents at 8 kHz is alt text, not a caption.
2. No terminal period on a claim label. The claim is a label, not a sentence. (A multi-clause antithesis follows the same drop-the-period rule; see rule 4.)
3. The canonical atom ID for traceability is a code comment or canonicalRefs entry, never visible caption text. Atom IDs (EVD-, CLM-, etc.) never render. See categories/composition/atom-id-exposure.md.
4. Two-clause antithesis captions. When the caption has the shape [X does A]. [Verdigris does B] (a two-clause comparison that mirrors an H1 antithesis), drop the terminal period, same rule as categories/typography/h1-punctuation.md. A period mid-caption parses the clauses; a terminal period adds weight the comparison doesn’t need. This carve-out applies when the caption is itself an antithesis. The antithesis is the one place a caption may run slightly past the <=7-word claim length, because the contrast itself is the claim: Device-cadence SNMP polling vs. 240,000 samples per window (no trailing period).
5. No artifact narration, no “how to read this”, no disclaimers. “Chart showing…”, “drag to compare”, “illustrative example” are all banned meta-language (see communicate-at-a-glance.md). If the figure needs them to be read, redesign the figure.

ResourceCard chip variant

The ResourceCard pattern (image + title + body) is the compact figure: it uses the same vertical rhythm but at a smaller register and inside a card frame.

Why these differ from the figcaption spec

The ResourceCard is a navigable object (clickable, hoverable) — the title needs to read as a link, not a caption. Hence 18px / 600 weight, vs 14px / 700 weight for the figcaption. The card body is description (one or two sentences before a “Read more →” chip), not a single-clause caption.

Compliant: Canvas viz, claim label

{/* The picture argues. The alt text describes it. The caption claims. */}
<figure className="vd-figure">
  <CanvasFrame>
    {/* Series + axis labels are drawn INSIDE the canvas, not in prose below */}
    <WaveformTrace aria-label="Three-phase load currents at 8 kHz over a 60-second window" />
  </CanvasFrame>
  <figcaption>Degrading rectifier caught 21 days early</figcaption>
</figure>

Also compliant: no caption

{/* A figure that argues at a glance ships with no visible caption. */}
<figure className="vd-figure">
  <CanvasFrame>
    <ResolutionComparison aria-label="Same signal at 1 Hz and 8 kHz; the 1 Hz trace is flat" />
  </CanvasFrame>
</figure>

Non-compliant

{/* Artifact description as a caption -- belongs in alt text, not the caption */}
<figcaption>Three-phase load currents at 8 kHz</figcaption>

{/* "How to read this" / interaction narration -- redesign the figure instead */}
<figcaption>Drag the slider to compare sampling rates</figcaption>

{/* Disclaimer language -- banned meta-language */}
<figcaption>Illustrative example of harmonic structure</figcaption>

{/* Caption carrying the argument the picture should carry (legend-as-prose) */}
<figcaption>The teal line is voltage, the purple line is current; note divergence</figcaption>

{/* Caption merged into body prose; lost the figure register */}
<>
  <WaveformTrace ... />
  <p>The above chart shows three-phase load currents at 8 kHz...</p>
</>

{/* Caption above the figure (only tables do this) */}
<figure>
  <figcaption>Degrading rectifier caught early</figcaption>
  <WaveformTrace ... />
</figure>

{/* Caption full body-prose width (76ch+) reading as paragraph escape */}
<figcaption style=>...</figcaption>

{/* Atom ID exposed as visible UI element */}
<figcaption>
  Degrading rectifier caught early <span className="atom-id">EVD-003</span>
</figcaption>

Where this applies

Sources

1. categories/whitepapers/body.md (existing) — .vd-figure pattern. Established the figure-number-eyebrow + below-the-figure caption layout for whitepapers. This rule generalizes to web.
2. Edward Tufte, The Visual Display of Quantitative Information (1983, 2nd ed. 2001). Chapter 6, on integrated text-and-graphic figures. Tufte’s principle: the caption is part of the figure, not separate commentary; vertical proximity (small gap) signals that integration.
3. Bringhurst, The Elements of Typographic Style, Chapter 2 “Rhythm & Proportion.” The 12px (visual→caption) gap is 0.75rem, a 4-grid multiple; the 4px (title→body) gap is 0.25rem, also a 4-grid multiple. Cited via 24ways “Compose to a vertical rhythm”.
4. tokens/typography/scale.json — caption-strong and body-small tokens were already defined; this rule specifies their composition.
5. Reference bar: product visuals that ship a roughly 4-word claim heading and zero visible captions. Stripe, Linear, Vercel, Cloudflare, Datadog. Mark Chung’s instrument-grade artifacts read the same way: the trace and the number argue; the caption claims or disappears. These are reference exemplars, not the authority; the authority is the principle in communicate-at-a-glance.md.

See also

• categories/composition/communicate-at-a-glance.md — the principle this caption rule serves; the meta-language ban and word budgets
• categories/whitepapers/body.md — print figure pattern
• categories/composition/atom-id-exposure.md — atom IDs belong in code comments / canonicalRefs, not visible UI
• rules/visual-rules.yml > composition.figure_caption — machine-enforceable rule