Example

Code

Copy the markup

import "@luz-ds/catalog/components/example.css";

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/example.min.css" integrity="sha384-6PMwsV5nwigGpYPyw438GJj5Dk1YJ3/7pLnMLEe0VWvR1iM/pgM131Vldh0IEwh7" crossorigin="anonymous">

A figure with the preview and, under it, the code. The code is optional:

<figure class="luz-example">
  <div class="luz-example__preview">
    <div class="luz-example__frame">
      <button class="luz-btn luz-btn--primary" type="button">Save changes</button>
    </div>
  </div>
  <div class="luz-example__code">
    <pre class="luz-code-block" data-lang="html" tabindex="0" aria-label="Markup of the example"><code>&lt;button class="luz-btn luz-btn--primary" type="button"&gt;Save changes&lt;/button&gt;</code></pre>
  </div>
</figure>

Variants and options

No modifier. The width is a custom property.

How it works

CSS from components/example.css of @luz-ds/catalog on core's code block and highlight.

• The preview and the code are one frame, so they read as one example. A long line scrolls inside the code block and never widens the figure.
• The frame's width is min(100%, var(--luz-example-w, 100%)): a width larger than the room does not widen the figure.
• The frame is a size container (container-type: inline-size). A block button fills the frame, not the window, and a rule of your own can answer to the frame with @container.
• Write the markup once and show it twice, as a preview and as escaped code: the reader sees what they copy.

Without JavaScript

Nothing changes in the frame. The code block is plain text in a region that scrolls and takes the focus, without the highlight and the copy button of core's script.

Keyboard and ARIA

• Order: the controls of the preview, then the code block.
• Code block: keep tabindex="0" and an aria-label on the <pre>: it scrolls, and without them a keyboard user cannot reach it or tell what it is.
• Preview: it is live, so what is in it works as it does anywhere. A picture that must not be used goes in Do and don't, whose stage is inert.

Contrast and focus are in the Design tab.

Design

When to use

Use the example to show a piece and the markup that makes it, in one frame, the code under the preview.

• A component, a pattern or a snippet that a reader will copy.
• A piece whose look depends on its width: set the frame's width.

When not to use

Do not use the example to show a mistake or code with nothing to preview.

• A picture of a mistake goes in Do and don't, which is inert.
• Code with nothing to show, such as a command, is a plain code block.

Do and don't

<button class="luz-btn luz-btn--secondary" type="button">Cancel</button>

Writing the content

• The sentence before the example says what it shows, in the imperative: "Add the primary class to make the main action."
• The code is the markup the preview is made of, word for word. Use real words in it, not "Lorem ipsum" and not "Button".
• Name in the sentence the one class or attribute the example teaches, so the reader knows where to look in the code.
• Name the code block: "Markup of the example", or "Markup of the primary button" when there are several.

Contrast and focus

The preview sits on the surface of the frame. The code block keeps core's colours: see the code block.

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 controls of the preview and the code block keep core's ring, 2 px of --luz-focus-ring.
• Edges: the border of the frame (--luz-divider) is decorative and has no minimum.
• Width: the frame never passes the room it has, so the page does not scroll sideways at 320px.

Tokens it uses

The 4 tokens that the .luz-example rules of catalog’s components/example.css read, 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-divider, --luz-surface

Spacing and sizing

--luz-space-md

Radius

--luz-radius-md

Keyboard and ARIA are in the Code tab.