Core · Show content

Figure

Shows an image, a chart or a diagram with a caption that says what it is.

components/figure.css
No JavaScript
Light · Dark · High contrast
No known issues

Example

A bar chart with a caption that says what it shows.

Requests per day, last six days.

Known issues

None known.

Code

Copy the markup

HTML

<figure class="luz-figure">
  <div class="luz-figure__media">
    <img src="requests.png" width="640" height="192" alt="Bar chart: requests rise every day, from 1,200 on Monday to 3,400 on Saturday.">
  </div>
  <figcaption class="luz-figure__caption">Requests per day, last six days.</figcaption>
</figure>

Variants and options

There are no modifiers.

Class	What it does
`.luz-figure`	A padded surface with a brand-coloured start border and rounded corners
`.luz-figure__media`	Rounds and clips the image, chart or code inside
`.luz-figure__caption`	Smaller, italic, secondary text colour

How it works

The native <figure> and <figcaption>, styled by components/figure.css. No JavaScript.

The caption names the figure for assistive technology.
A bare <figure> with no class also gets a simple style from the base elements.

Without JavaScript

Nothing changes: a figure is HTML and CSS.

Keyboard and ARIA

A figure is not interactive and takes no focus.

The media needs its own text alternative: alt on an <img>, or role="img" and aria-label on an inline <svg>.
A chart also needs its numbers as text: in the alt text, the caption or a table next to it.

Contrast and focus are in the Design tab.

Design

When to use

Use a figure for a chart, an image, a diagram or a code sample that the text refers to and that needs a caption.

When not to use

Do not use a figure for decoration.

A decorative image gets alt="" and no figure.
For a picture in a box of fixed shape, use the image frame.

Do and don't

Do A caption that says what the figure shows, and for what period.

Don't “Figure 1” as the caption: the reader learns the number, not what the chart says.

Writing the content

The caption says what the figure shows, and for what period or scope.

The alt text says what the reader would see: the trend, not "chart".
Do not repeat the caption in the alt text.

Contrast and focus

The caption is secondary text on the figure's surface.

Part	Colour on background	Light	Dark	High contrast	Needs
Caption	`--luz-text-secondary` on `--luz-surface`	6.4:1	6.9:1	19.3:1	4.5:1

Measured from the token values of each mode, rounded down. Needs is the WCAG 2.2 AA minimum: 4.5:1 for text, 3:1 for focus rings, borders and icons.

Focus: the figure takes none.
Graphics: the colours inside the media are yours: keep the parts of a chart that carry meaning at 3:1 against their background (WCAG 1.4.11). The brand start border is decorative.

Tokens it uses

The 7 tokens that components/figure.css reads, by family. Each family links to its page, with the values in every mode. In Figma they are variables with the same names: see Tokens in Figma.

Color: --luz-brand-primary, --luz-surface, --luz-text-secondary
Spacing and sizing: --luz-space-lg, --luz-space-sm, --luz-space-xs
Radius: --luz-radius-md

Keyboard and ARIA are in the Code tab.