Usage

Start with these tokens when customizing figures:

--figure-spacing-top and --figure-spacing-bottom for vertical rhythm

--figure-max-width (plus mobile/print variants) for breakout width

--figure-background, --figure-border-width, and --figure-border-radius for containers

--figure-caption-* and --figure-label-* for caption typography

Figure captions and labels use the --figure-caption-* and --figure-label-* tokens, which align with the shared caption/label system for consistent typography.

Tokens

Spacing Tokens

Control vertical separation and layout spacing for figures.

Token	Description	Default Value
`--figure-spacing-top`	Top margin (automatic responsive scaling)	`var(--content-spacing)`
`--figure-spacing-bottom`	Bottom margin (automatic responsive scaling)	`var(--content-spacing)`

Layout Tokens

Controls the breakout width behavior for figure containers.

Token	Description	Default Value
`--figure-max-width`	Maximum width for figure container	`var(--content-breakout-width)`
`--figure-max-width-mobile`	Max width for figure on mobile	`var(--content-breakout-width-mobile)`
`--figure-max-width-print`	Max width for figure in print	`100%`

Container Styling Tokens

Optional visual isolation through backgrounds and borders (defaults to minimal appearance).

Token	Description	Default Value
`--figure-background`	Background color	`transparent`
`--figure-background-dark`	Background color for dark mode	`transparent`
`--figure-background-print`	Background color for print	`transparent`
`--figure-border-width`	Border thickness	`0`
`--figure-border-color`	Border color	`var(--border-color-subtle)`
`--figure-border-color-dark`	Border color for dark mode	`var(--border-color-subtle-dark)`
`--figure-border-color-print`	Border color for print	`var(--border-color-default-print)`
`--figure-border-radius`	Corner rounding	`var(--border-radius-default)`
`--figure-padding`	Internal padding around figure content	`0`

Content Layout Tokens

Control figure content positioning and width constraints.

Token	Description	Default Value
`--figure-content-display`	Display type for figure content	`block`
`--figure-content-max-width`	Maximum width for figure content	`100%`
`--figure-content-margin-horizontal`	Horizontal margins for centering	`auto`

Caption Layout and Typography Tokens

Layout and typography styling for figure captions (inherits from caption and label tokens).

Token	Description	Default Value
`--figure-caption-font-family`	Font family for captions	`var(--caption-font-family)`
`--figure-caption-font-size`	Font size for captions	`var(--caption-font-size)`
`--figure-caption-color`	Text color (automatic dark mode)	`var(--caption-color)`
`--figure-caption-spacing-top`	Gap between image and caption	`var(--caption-spacing)`
`--figure-caption-line-height`	Line height for caption text	`var(--caption-line-height)`
`--figure-caption-align`	Text alignment (left, center, right, justify)	`var(--caption-align)`
`--figure-caption-max-width`	Maximum width for caption text	`var(--caption-max-width)`
`--figure-label-font-weight`	Font weight for figure labels	`var(--label-font-weight)`
`--figure-label-font-style`	Font style for figure labels	`var(--label-font-style)`
`--figure-label-color`	Text color for figure labels	`var(--label-color)`

Overlay Tokens

Defaults for SVG annotation layers rendered on top of figures and code chunks. A single base color (--figure-overlay-color) drives all derived defaults — override it to restyle all overlays at once, or override individual tokens for fine-grained control.

These tokens apply to both figure overlays and code chunk overlays (when the code chunk has a figure label). Token definitions live in figures.css; code chunk overlay rules in code.css reference the same tokens via the :root cascade.

Token	Description	Default Value
`--figure-overlay-color`	Base color — sets the CSS `color` property on the SVG so that `currentColor` references in text, markers, and arrowheads all resolve to the themed overlay color	`var(--color-gray-600)`
`--figure-overlay-color-dark`	Base color in dark mode	`var(--color-gray-400)`
`--figure-overlay-color-print`	Base color in print (forced high-contrast)	`var(--color-gray-800)`
`--figure-overlay-stroke-color`	Stroke color for shapes (override separately from `color` when strokes need a different shade)	`var(--figure-overlay-color)`
`--figure-overlay-stroke-color-dark`	Stroke color in dark mode	`var(--figure-overlay-color-dark)`
`--figure-overlay-stroke-width`	Stroke width (unitless, scales with viewBox)	`2`
`--figure-overlay-font-family`	Font family for `<text>` elements	`var(--font-family-sans)`
`--figure-overlay-font-size`	Font size (unitless, scales with viewBox)	`16`
`--figure-overlay-font-weight`	Font weight for `<text>` elements	`var(--font-weight-semibold)`

How coloring works: The CSS sets color: var(--figure-overlay-color) on the overlay SVG element. Built-in definitions (arrowheads, marker symbols) and generated <text> elements use fill="currentColor" and stroke="currentColor", the standard SVG idiom. This means --figure-overlay-color is the single source of truth for text fills, arrowhead fills, and marker strokes — all via currentColor. Strokes on shapes use --figure-overlay-stroke-color separately so themes can differentiate if needed.

Dark mode: In dark mode, all overlay color tokens automatically switch to their -dark variants. The default (gray-400 in dark mode) provides reliable contrast on dark backgrounds and avoids clashing with accent-colored plot elements.

Print: In print, all overlay color tokens are forced to --figure-overlay-color-print (default: --color-gray-800) for reliable high-contrast output regardless of theme customization.

Unitless values: --figure-overlay-stroke-width and --figure-overlay-font-size are unitless numbers that scale with the SVG viewBox coordinate system. The defaults (2 and 16) work well for overlays with viewBox dimensions in the 400–800 unit range. For very small or very large viewBoxes, override these per-element with explicit SVG attributes.

Note

Overlay tokens provide defaults for common inline SVG annotation content: shapes, lines, text labels, and common marker arrowheads. They do not tokenize every SVG feature. Properties such as stroke-dasharray, gradients, filters, and uncommon marker child shapes still need explicit SVG markup or attributes. When you need a different treatment on a specific element, use explicit SVG attributes such as stroke, stroke-width, fill, or font-size on that element. For text labels and marker arrowheads, the theme defaults are only applied when those attributes are absent, so explicit per-element SVG attributes continue to work reliably.

Examples

Default Figures

Standard figure styling with automatic responsive spacing and dark mode support:

:root {
  /* No design token overrides */
}

Figure 1: An example figure demonstrating default styling with a placeholder image and caption.

Isolated Figures

Figures with background and border for enhanced visual separation:

:root {
  --figure-background: var(--surface-sunken);
  --figure-border-width: 1px;
  --figure-border-color: var(--border-color-default);
  --figure-padding: var(--space-4);
  --figure-border-radius: var(--radius-lg);
}

Figure 2: A figure with background, border, and padding to create a distinct visual container.

Scholarly Article Figures

Enhanced spacing and typography for scholarly documents:

:root {
  --figure-spacing-top: calc(var(--content-spacing) * 2);
  --figure-spacing-bottom: calc(var(--content-spacing) * 2);
  --figure-caption-spacing-top: var(--content-spacing);
  --figure-caption-font-size: var(--font-size-xs);
  --figure-caption-line-height: var(--line-height-md);
  --figure-caption-align: justify;
}

Figure 3: Scholarly figures benefit from increased vertical spacing, larger gaps between image and caption, smaller caption font sizes, and justified text alignment for a formal academic appearance.

Centered Captions

Symmetrical layout with centered caption text:

:root {
  --figure-caption-align: center;
  --figure-caption-spacing-top: var(--space-3);
}

Figure 4: Centered captions work well for symmetrical images and formal layouts where the caption should be balanced visually beneath the figure content.

Compact Figures

Reduced spacing for documentation or high-density layouts:

:root {
  --figure-spacing-top: var(--space-4);
  --figure-spacing-bottom: var(--space-4);
  --figure-caption-spacing-top: var(--space-2);
  --figure-caption-font-family: var(--font-family-sans);
  --figure-caption-font-size: var(--font-size-xs);
  --figure-caption-line-height: var(--line-height-xs);
}

Figure 5: Compact figures with minimal spacing, smaller sans-serif captions for technical documentation.

Multi-Paragraph Captions

Captions can contain multiple paragraphs with proper spacing. Using background and borders makes it clear that all paragraphs belong to the figure:

:root {
  --figure-background: var(--surface-sunken);
  --figure-border-width: 1px;
  --figure-border-color: var(--border-color-default);
  --figure-padding: var(--space-4);
  --figure-caption-line-height: var(--line-height-md);
  --figure-caption-spacing-top: var(--space-4);
}

Figure 6: This figure demonstrates multi-paragraph captions. The first paragraph introduces the figure content and provides context.
Subsequent paragraphs maintain consistent spacing through the `--figure-caption-spacing-top` token, ensuring proper visual hierarchy within the caption while remaining distinct from the image above. The background and border make it clear that both paragraphs are part of the figure.

Overlays

Overlay elements inherit defaults from the --figure-overlay-* tokens. No explicit SVG presentation attributes are needed — shapes get themed stroke and fill, text gets themed color and font:

:root {
  /* No design token overrides — defaults apply */
}


::: figure

![](https://placehold.co/600x300/6395f8/ddd?text=overlay)

```svg overlay
<svg viewBox="0 0 600 300" xmlns="http://www.w3.org/2000/svg">
  <circle cx="300" cy="150" r="60"/>
  <text x="370" y="155">Center</text>
  <rect x="30" y="30" width="160" height="80"/>
  <text x="40" y="125">Region A</text>
</svg>
```

A figure with themed overlay annotations using default tokens.

:::

Figure 7: A figure with themed overlay annotations using default tokens.

Overlay Theme Overrides

Mix defaults and explicit overrides in the same overlay. Elements with explicit attributes keep their specified values; elements without use the theme:


::: figure

![](https://placehold.co/600x300/6395f8/ddd?text=override)

```svg overlay
<svg viewBox="0 0 600 300" xmlns="http://www.w3.org/2000/svg">
  <circle cx="300" cy="150" r="50"/>
  <text x="360" y="155">Themed</text>
  <circle cx="100" cy="75" r="30" stroke="orange" stroke-width="4"/>
  <text x="140" y="80" fill="orange">Explicit orange</text>
</svg>
```

Default themed circle and label alongside explicitly orange overrides.

:::

Figure 8: Default themed circle and label alongside explicitly orange overrides.

Custom Overlay Color

Override --figure-overlay-color to restyle all overlay elements at once:

:root {
  --figure-overlay-color: var(--color-red-600);
  --figure-overlay-color-dark: var(--color-red-400);
}

Tips

Isolation: Use --figure-background and --figure-border-* to add containers; leave them transparent for minimal layouts.

Captions: Use --figure-caption-align and --figure-caption-max-width to control caption readability independently of figure width.

Labels: Figure labels inherit shared label tokens; override --figure-label-* only when you need to break that alignment.

Print overrides: Use --figure-background-print and --figure-border-color-print for print-specific adjustments.

Overlays: Override --figure-overlay-color to change all overlay annotations at once; override individual tokens like --figure-overlay-stroke-color or --figure-overlay-font-family for fine-grained control. Use --figure-overlay-color-print for print-specific overlay styling.