Structure and landmarks Rule

Definition lists must be built from matching terms and descriptions definition-list

A dl is a list of terms and their descriptions: each dt (the term) is followed by one or more dd (the description). Screen readers use that pairing to announce 'term, description'. Put anything else straight inside the dl, or start with a dd, and the pairs break. The only extras allowed directly inside a dl are a div around each group, script and template.

WCAG 2.2 A 1.3.1 Info and Relationships

Websight reports this as <dl> elements must only directly contain properly-ordered <dt> and <dd> groups, <script>, <template> or <div> elements

Who it affects

A patient who is blind, reading a GP surgery's clinic list hears clinic names and times out of step, so the flu clinic seems to be on Thursday when that is the diabetes clinic.

Someone with a cognitive disability using a screen reader loses the term-then-description rhythm that makes this kind of list easy to follow.

Someone using the browser's reader view sees the layout jump, because the browser has to guess where each group ends.

Broken versus fixed

Both examples are live and rendered in a sandboxed frame. The broken one is deliberately broken.

Broken

A heading and a paragraph sit directly inside the dl. The pairing breaks, and some screen readers stop announcing it as a definition list at all.

Fixed

Each clinic name is a dt and each time a dd. Announced as: Flu clinic, Tuesdays 2pm to 5pm. The heading and note sit outside the list.

Show the markup behind both examples
Broken
<style>body{font-family:system-ui;margin:0;padding:16px}dl{margin:0}dt{font-weight:600;margin-top:6px}dd{margin:0 0 0 16px}h3{font-size:16px;margin:0}</style>
<dl>
  <h3>Weekly clinics</h3>
  <dt>Flu clinic</dt>
  <dd>Tuesdays, 2pm to 5pm</dd>
  <p>Please book by phone.</p>
  <dt>Diabetes review</dt>
  <dd>Thursdays, 9am to 12pm</dd>
</dl>
Fixed
<style>body{font-family:system-ui;margin:0;padding:16px}dl{margin:0}dt{font-weight:600;margin-top:6px}dd{margin:0 0 0 16px}h3{font-size:16px;margin:0}</style>
<h3>Weekly clinics</h3>
<dl>
  <dt>Flu clinic</dt>
  <dd>Tuesdays, 2pm to 5pm</dd>
  <dt>Diabetes review</dt>
  <dd>Thursdays, 9am to 12pm</dd>
</dl>
<p style="margin:8px 0 0">Please book by phone.</p>

Test it by hand in two minutes

  1. Right click the list, choose Inspect, and read the children of the dl in order. You should see dt, then one or more dd, then dt again, with nothing else between them except div wrappers.
  2. Check that the first child is a dt (or a div holding a dt) and that no dt is left without a dd.
  3. Move through it with VoiceOver. It announces 'definition list' on entry and pairs each term with its description.

The fix

Before
<dl>
  <h3>Weekly clinics</h3>
  <dt>Flu clinic</dt>
  <dd>Tuesdays, 2pm to 5pm</dd>
  <p>Please book by phone.</p>
</dl>
After
<h3>Weekly clinics</h3>
<dl>
  <dt>Flu clinic</dt>
  <dd>Tuesdays, 2pm to 5pm</dd>
</dl>
<p>Please book by phone.</p>

Move anything that is not a term or a description outside the dl. Headings go before it, notes after it.

Grouping pairs for styling

Before
<dl>
  <dt>Flu clinic</dt>
  <dd>Tuesdays</dd>
  <dt>Diabetes review</dt>
  <dd>Thursdays</dd>
</dl>
After
<dl>
  <div><dt>Flu clinic</dt><dd>Tuesdays</dd></div>
  <div><dt>Diabetes review</dt><dd>Thursdays</dd></div>
</dl>

A div around each dt and dd group is allowed and gives you something to style as a row or card.

Description before its term

Before
<dl>
  <dd>Tuesdays, 2pm to 5pm</dd>
  <dt>Flu clinic</dt>
</dl>
After
<dl>
  <dt>Flu clinic</dt>
  <dd>Tuesdays, 2pm to 5pm</dd>
</dl>

The term always comes first.

Not really a definition list

Before
<dl>
  <dt>Flu clinic</dt>
  <dt>Diabetes review</dt>
  <dt>Asthma review</dt>
</dl>
After
<ul>
  <li>Flu clinic</li>
  <li>Diabetes review</li>
  <li>Asthma review</li>
</ul>

A dl with no descriptions is a plain list. Use ul.

Common mistakes

  • Using dl for any two-column layout, such as a form, because it lines up neatly.
  • Wrapping each pair in a span or an li instead of a div.
  • Adding a dt with no dd, or a dd with no dt, to make the spacing come out right.
  • Nesting a dl inside a dd and forgetting to close the outer dd.

WCAG criteria this rule maps to

axe-core tags this rule as WCAG 2.2 level A. It is one of the checks for:

The scanner can see direct children of a dl that are not dt, dd, div, script or template, and dt or dd elements out of order. It cannot judge whether the content is really a set of terms and descriptions, or whether each pair matches in meaning. Automated tools find only part of the accessibility problems on a page; a pass on this rule is not a pass on the criterion.

A Terms and descriptions must sit inside a definition list dlitem dt and dd only mean term and description when they are inside a dl. A Lists must only contain list items list A ul or ol tells a screen reader 'list, N items' and lets the person jump item by item. A List items must sit inside a list listitem An li is only a list item when its parent is a ul, ol or menu.

Scan your own page for this and 63 other checks

Open any page in Chrome, click Websight, and get a score out of 100 with every issue explained and a draft fix snippet per element.

Add Websight to Chrome

Free scans, no account, nothing leaves your computer. Automated tools find only part of the problems; the extension says so on every report.