Prose

Code

Copy the markup

<div class="luz-prose">
  <!-- What the editor or the Markdown writes, as it is -->
  <p>Since March 2016, a group of volunteers has read the tide gauge…</p>
  <h2 id="method">How the readings were taken</h2>
  <p>…</p>
  <ul class="wp-block-list">
    <li>…</li>
  </ul>
  <figure>
    <img src="gauge.jpg" width="1200" height="800" alt="The tide gauge in the port, a post marked in centimetres">
    <figcaption>The gauge at low tide.</figcaption>
  </figure>
</div>

Variants and options

There are no modifiers.

How it works

CSS only, in components/prose.css. Every selector is inside :where(), so a LUZ component inside the text, or a rule of yours, wins.

• Line length. Each block of the wrapper is at most --luz-prose-measure wide. Figures, tables, code blocks, images, videos and .luz-table-wrap take the whole width of the wrapper, never more.
• Space between blocks. A block starts --luz-space-md below the one before it. A heading or a rule starts further down (--luz-space-xl), and the block after a heading sits closer (--luz-space-sm). Margins, not a gap: a component inside keeps its own margin, and the two collapse.
• Lists. Every list gets its indent and markers back, with a class or without one (an editor's ul.wp-block-list), except a list with a layout object (.o-grid, .o-stack) or a LUZ component class.
• Inline code has the look of .luz-code-inline. Long words and addresses break rather than push the page sideways.
• Bare elements take the same three steps between blocks in luz.css, so the two agree; prose is in a later layer, so it wins where they meet. Prose adds the line length and the lists.

Without JavaScript

Nothing changes: prose is CSS.

Keyboard and ARIA

Prose takes no focus and adds no role. Tab reaches the links and controls inside it, in source order.

• A long <pre> scrolls sideways inside itself. To scroll it with the keyboard, give it tabindex="0", role="region" and a name, as core's code block does.
• The headings inside make the outline of the text: start at the level under the page's title, and do not skip one.

Contrast and focus are in the Design tab.

Design

When to use

Use prose around running text whose markup you do not write block by block: the body of a post or a page from a CMS editor, Markdown, a help article.

When not to use

Do not put prose around a whole page or an interface: the header, the navigation, forms and cards lay themselves out.

• For a column of blocks you build yourself, use .o-stack.
• For one or two lines inside a component, such as a card's text, use the component's own classes.

Do and don't

Writing the content

Write for someone who reads the first words of each line and skips the rest.

• One idea a paragraph. Put the point first.
• Headings in order, in sentence case, that say what the section is about.
• A list for three or more things of the same kind; a sentence for two.
• Links that say where they go, and figures with a caption that says what they show.

Contrast and focus

The text and the links keep the colours of core's elements; inline code is the code colour on a muted surface.

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: links keep core's 2 px --luz-focus-ring outline, 2 px outside the text.
• Links: underlined, so they are not marked by colour alone (WCAG 1.4.1).

Tokens it uses

The 11 tokens that components/prose.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-color-code, --luz-divider, --luz-surface-muted

Spacing and sizing

--luz-space-2xs, --luz-space-3xs, --luz-space-md, --luz-space-sm, --luz-space-xl, --luz-space-xs

Typography

--luz-text-xs

Radius

--luz-radius-sm

Keyboard and ARIA are in the Code tab.