Definition lists must contain ordered dt then dd elements

Definition lists must contain only dt and dd in the correct order

Use dl so that each group has one or more dt terms followed by one or more dd definitions. Only dt, dd, optional grouping div, and script/template may be direct children of dl.

Why It Matters

Assistive technologies announce definition lists and their items using the underlying semantics. If the structure is wrong, users hear confusing or missing relationships between terms and definitions.

People using screen readers rely on the dt→dd sequence to understand which definition belongs to which term. Incorrect order or stray elements break that relationship. This supports WCAG 2.2 Success Criterion 1.3.1 (Info and Relationships).

Common Causes

• dd appears before its corresponding dt
• Elements other than dt, dd, div, script, or template placed directly inside dl (for example p, h3, li)
• Using ul/li or tables to mimic definitions instead of dl/dt/dd
• Mixing multiple dt and dd without clear grouping, making pairs ambiguous
• Wrapping groups in div but placing content other than dt/dd inside that div
• Visual reordering with CSS that hides the underlying dt→dd sequence

How to Fix

1. Use the correct container
   • Wrap the list in a dl element.
2. Keep allowed children only
   • Direct children of dl must be: dt, dd, div (as a group wrapper), or script/template. Do not place headings, paragraphs, list items, or other elements directly under dl.
3. Maintain correct order
   • For each group: one or more dt (terms) followed by one or more dd (definitions). Never put dd before dt.
4. Group for styling when needed
   • If you need to style or separate pairs, wrap each group in a div. That div must contain only dt and dd elements.
5. Use multiple dt or dd when appropriate
   • Multiple dt can define synonyms for the same concept. Multiple dd can provide multiple definitions or notes for a term.
6. Keep the DOM order meaningful
   • Ensure the reading order (DOM) reflects the intended term→definition relationship, even if CSS changes the visual layout.

Recommendation: Validate your HTML and use a linter to catch invalid children inside dl.

How to Test

Keyboard check

• Tab through the page and ensure focus moves logically around, not into broken or stray items inside the definition list.

Screen reader check

• With a screen reader (NVDA/JAWS/VoiceOver), navigate to the definition list.
• Confirm it announces a definition list and the expected item count.
• Move item by item: each dt should be read as a term and followed by the related dd as a definition.
• Ensure synonyms (multiple dt) are followed by their shared dd.

Programmatic/DOM check

• Validate allowed children and order:

const badChildren = [...document.querySelectorAll('dl > *:not(dt):not(dd):not(div):not(script):not(template)')];
console.assert(badChildren.length === 0, 'Found invalid direct children in dl');

document.querySelectorAll('dl').forEach(dl => {
  const children = [...dl.children];
  for (let i = 0; i  children.length; i++) {
    const node = children[i];
    if (node.tagName === 'DIV') {
      const divKids = [...node.children];
      if (divKids.some(el => !['DT','DD'].includes(el.tagName))) {
        console.error('Group div contains non-dt/dd elements', node);
      }
    }
  }
});

Mobile/touch check

• Spot-check with mobile screen readers (TalkBack/VoiceOver) to ensure the same term→definition reading order.

Good Example

<dl class="spec-glossary">
  <div class="pair">
    <dt>NYC</dt>
    <dt>New York City</dt>
    <dd>The most populous city in the United States.</dd>
  </div>
  <div class="pair">
    <dt>GDP</dt>
    <dd>Gross domestic product, the value of goods and services produced.</dd>
    <dd>Often used to compare economic output between regions.</dd>
  </div>
</dl>

Bad Example

<dl>
  <dd>A brewed drink from roasted beans.</dd>
  <dt>Coffee</dt>
  <li>Unrelated list item</li>
  <div>
    <h3>Milk</h3>
    <p>White cold drink</p>
  </div>
  <dt>Tea</dt>
</dl>

Issues shown:

• dd appears before its dt (Coffee)
• li is an invalid direct child of dl
• div contains h3/p instead of dt/dd
• Unclear pairing for Tea (no dd follows)

Quick Checklist

• dl wraps the entire definition list
• Only dt, dd, div (grouping), script, or template are direct children of dl
• Each group has one or more dt followed by one or more dd (never dd first)
• Optional div groups contain only dt and dd
• Multiple dt or dd used only when they describe the same concept
• DOM order reflects the intended reading order
• Verified with a screen reader that terms and definitions are announced correctly