Rule ID: ace-struct-def-list

Validate definition list (dl) elements contain only properly structured dt and dd pairs

WCAG 2.0 (A) - WCAG 2.2 (A) 4.1.2: Name, Role, Value Blind Deafblind User Impact

What This Rule Checks

A definition list (<dl>) is used to group terms and their corresponding definitions. The list should only contain two types of elements: <dt> for the term being defined and <dd> for the definition. These elements must follow a specific order, where each <dt> is followed by one or more <dd> elements.

Who Is Affected

This issue primarily affects: Blind users, who rely entirely on screen readers or braille displays to navigate and interact with content; Deafblind users, who rely on braille displays and cannot access visual or auditory content.

Why This Matters

Screen readers use the definition list structure to announce term-definition pairs. Invalid child elements break this semantic relationship, causing assistive technologies to present the content as unstructured text.

How to Fix

Use the Correct Elements for Definition Lists

Ensure that each term is contained in a <dt> element and each corresponding description is in a <dd> element. These should be wrapped in a <dl> (definition list) element.

Avoid Nesting Definitions Outside of a <dl>

All <dt> and <dd> elements must be contained within a <dl> tag. Avoid placing terms and definitions outside of the <dl> container.

Code Examples

Incorrect Markup Solutions:

Code example

<!-- Invalid children in definition list -->
<dl>
  <div class="term">HTML</div>
  <div class="def">HyperText Markup Language</div>
</dl>

Copy

Correct Markup Solutions:

Code example

<!-- Properly structured definition list -->
<dl>
  <dt>HTML</dt>
  <dd>HyperText Markup Language</dd>

  <dt>CSS</dt>
  <dd>Cascading Style Sheets</dd>
</dl>

<!-- Grouped with div (valid in HTML5) -->
<dl>
  <div>
    <dt>HTML</dt>
    <dd>HyperText Markup Language</dd>
  </div>
</dl>

Copy

Common Mistakes to Avoid

Using <p> or <span> elements directly inside <dl> instead of <dt>/<dd>.
Nesting a <dl> inside another <dl> without proper structure.
Having <dd> elements without a preceding <dt>.

Tip: Proper document structure enables assistive technologies to present content meaningfully. Headings, lists, and semantic HTML elements create a navigable outline of the page that screen reader users depend on.

Related WCAG Criteria

• 4.1.2: Name, Role, Value