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)`

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.

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.