probeo

How to fix a definition list with the wrong structure?

definition-list page

The issue

A definition list ties each term to its description: a glossary, a specification table, a set of FAQs or product details. When the markup is broken, a screen reader can’t present the pairs as pairs, so a listener hears terms and descriptions without knowing which belongs to which.

The cause is one of two structural mistakes. Either a <dl> has something other than <dt>, <dd>, <div>, <script> or <template> directly inside it, or a <dt> or <dd> sits somewhere other than inside a <dl>. WCAG 1.3.1 requires structure conveyed visually to be available in the markup too.

Scope

Two rules check definition lists:

  • definition-list checks each visible <dl>. Direct children may be <dt>, <dd>, <div>, <script> or <template>; anything else is reported, naming the elements found. A <dl> given a role other than list, none or presentation is skipped.
  • dlitem checks each visible <dt> and <dd>. It must be inside a <dl>, either directly or through <div> wrappers.

The rule checks which elements appear, not the order of terms and descriptions. Elements hidden with hidden, aria-hidden="true", or an inline display: none or visibility: hidden are skipped.

How to check you have it

  • In probeo: the page reports definition-list, “<dl> elements must only directly contain properly-ordered <dt> and <dd> groups, <script>, <template> or <div> elements”, or dlitem, “<dt> and <dd> elements must be contained by a <dl>”. Both have serious impact and map to WCAG 1.3.1.
  • By hand: in the browser’s DevTools, inspect each <dl> and its direct children, and check that every <dt> and <dd> has a <dl> above it.
  • With a tool: axe DevTools reports both rules by the same names.

The fix

Keep only <dt>, <dd> and grouping <div> elements directly inside each <dl>, and keep every <dt> and <dd> inside one.

To group a term with its description, for styling, wrap the pair in a <div>; that is allowed. Put any other content inside a <dd> or outside the list.

<dl>
  <div>
    <dt>Turnaround</dt>
    <dd>Two business days</dd>
  </div>
  <div>
    <dt>Support</dt>
    <dd>Email, weekdays</dd>
  </div>
</dl>

Done when: every <dl> holds only allowed children, every term and description sits in a <dl>, and the check above comes back clean.

Do not

  • Do not put a <p> or <span> directly inside a <dl>.
  • Do not use <dt> and <dd> outside a <dl> for their default indentation.
  • Do not wrap a pair in anything other than a <div>.

FAQ

When should I use a definition list?

When the content is a set of name and value pairs: a glossary, specifications, metadata such as author and date. For a sequence of items without names, a <ul> or <ol> fits better.

Can one term have several descriptions?

Yes. A <dt> can be followed by several <dd> elements, and several <dt> elements can share one <dd>.

Does the order of dt and dd matter?

It matters to anyone reading the list, since a description belongs to the term before it. This rule checks which elements are present, not their order, so check the order yourself.

Which product detects this

Probeo checks this on every page of your site as part of Site Clarity. This page explains one instance; the product tells you every page that has it.