Skip to main content

Catalog · Documentation

Do and don't

A Do and a Don't, one example to follow and one to avoid, each with its reason, side by side when there is room.

Fits best: docs — a page that teaches by showing what to do and what to avoid

Example

A Do and a Don’t about the title of a page.

Do Title a page for what it lets the reader do.
Don't Use a title that fits any page: "Introduction" tells the reader nothing.

A Do and a Don't.

The word, the mark before it and the frame (solid or dashed) say which is which, so the colour is never the only cue. The two stack on a narrow screen.

Known issues

In browsers without alternative text for generated content (Safari before 17.4, Firefox before 128), a screen reader may read the tick or the cross before "Do" or "Don't". The word that follows is always read.

Not tested with a screen reader.

Code

Copy the markup

Bundler 
import "@luz-ds/catalog/components/do-dont.css";
HTML 
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@luz-ds/catalog@0.3.0/dist/components/do-dont.min.css" integrity="sha384-Oy/gLexm/R2x1z6J/k+HPFqeZFukZ9a8dRAA4oXn0+KTbjg3uYSlaRV5fhdnM+UK" crossorigin="anonymous">

A pair: the Do first, then the Don't. Each is a figure whose caption says why:

HTML 
<div class="luz-do-dont">
  <figure class="luz-do-dont__item luz-do-dont__item--do">
    <figcaption><strong class="luz-do-dont__verdict">Do</strong> Title a page for what it lets the reader do.</figcaption>
    <div class="luz-do-dont__stage" inert aria-hidden="true">
      <h3>Install the command line tool</h3>
    </div>
  </figure>
  <figure class="luz-do-dont__item luz-do-dont__item--dont">
    <figcaption><strong class="luz-do-dont__verdict">Don't</strong> Use a title that fits any page: "Introduction" tells the reader nothing.</figcaption>
    <div class="luz-do-dont__stage" inert aria-hidden="true">
      <h3>Introduction</h3>
    </div>
  </figure>
</div>

Variants and options

One block, its parts, and two modifiers for the two verdicts.

ClassEffect
.luz-do-dont
On a <div>: the pair, in columns of at least 17.5rem. Side by side when there is room, stacked below
.luz-do-dont__item
On each <figure>: a framed box with the caption and the stage
.luz-do-dont__item--do
A solid frame in the success colour
.luz-do-dont__item--dont
A dashed frame in the danger colour
.luz-do-dont__verdict
On a <strong> that starts the caption: "Do" or "Don't", in the colour of its frame, with a tick or a cross before it
.luz-do-dont__stage
The picture: a bordered box on the page surface. Make it inert and aria-hidden="true". For a mistake that would itself be a barrier, use a pre.luz-code-block in its place

How it works

CSS from components/do-dont.css of @luz-ds/catalog. It draws the verdict three ways; the words are yours.

  • The verdict is a word first. The tick or the cross before it, the solid or dashed frame and the colour are extra cues, and none is the only one.
  • The tick and the cross are generated content with an empty alternative, so a screen reader does not read them.
  • The stage is inert and hidden from assistive technology: it is a picture, and the caption says what it shows. Nothing in it takes focus or is announced.
  • A mistake that would be a barrier when live, such as low contrast or wrong semantics, is shown as code in a pre.luz-code-block, never as a live stage.
  • Write the Do first, then its Don't. A page can have several pairs, one after another.

Without JavaScript

Nothing changes. The stage is inert by its attribute, and the pair is CSS.

Keyboard and ARIA

  • Order: the Do, then the Don't. Each is a <figure> with a <figcaption>, read as the caption of its picture.
  • Stage: inert keeps focus and clicks out of it, and aria-hidden="true" keeps it out of the accessibility tree. Do not put a link or a field in it that the reader should use.
  • Code stage: a pre.luz-code-block keeps tabindex="0" and an aria-label, as it scrolls.

Contrast and focus are in the Design tab.

Design

When to use

Use Do and don't to teach a rule by contrast: the reader sees the right way next to the wrong one.

  • A lesson that is easier to see than to say, such as a title, a label or a spacing.
  • One pair for each lesson, and the Don't is a mistake people make.

When not to use

Do not use it for a rule with nothing to compare, or to show a piece that works.

  • To show how a piece looks and is built, use the example.
  • Do not invent a mistake nobody makes to fill the Don't.
  • Do not show a live failure. A contrast or semantics failure goes in code.

Do and don't

Do Show one thing in the stage, the one the caption is about.
Don't Put several things in the stage: the reader cannot tell which one the caption is about.

Writing the content

  • The verdict is "Do" or "Don't", with the apostrophe, followed by a space.
  • The reason is one sentence, two at most. A Do starts with a verb; a Don't says what goes wrong for the reader.
  • The two stages show the same thing, changed in one way. If they differ in three ways, the reader cannot tell which one matters.
  • The example is made of real words: the name of a task, not "Lorem ipsum".

Contrast and focus

The caption sits on the surface of the frame and the stage on the page surface. The verdict and the frame carry the same colour.

PartColour on backgroundLightDarkHigh contrastNeeds
Do
--luz-color-success on --luz-surface
5.5:1
11.6:1
9.3:1
4.5:1
Don't
--luz-color-danger on --luz-surface
5.5:1
10.8:1
9.3:1
4.5:1
Caption
--luz-text-primary on --luz-surface
16.5:1
14.0:1
21.0:1
4.5:1
Stage text
--luz-text-primary on --luz-surface-page
15.8:1
15.1:1
21.0:1
4.5:1
Frame of the Do
--luz-color-success on --luz-surface
5.5:1
11.6:1
9.3:1
3:1
Frame of the Don't
--luz-color-danger on --luz-surface
5.5:1
10.8:1
9.3:1
3: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: nothing in a live stage takes focus. A code stage keeps core's ring, 2 px of --luz-focus-ring.
  • Not by colour alone: the word, the mark before it and the solid or dashed frame say which is which (WCAG 1.4.1).
  • Edges: the border of the stage (--luz-divider) is decorative and has no minimum.

Tokens it uses

The 11 tokens that the .luz-do-dont rules of catalog’s components/do-dont.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.

Spacing and sizing
--luz-space-md, --luz-space-sm
Typography
--luz-font-sans
Radius
--luz-radius-md, --luz-radius-sm

Keyboard and ARIA are in the Code tab.

Last updated · Edit this page · Report a problem