Definition list structure: what belongs inside a dl

What a definition list is

<dl> pairs terms with descriptions: a glossary, a set of metadata fields, a key-value table without the table. Screen readers announce the pairing, so a term is read together with the description that follows it.

The pairing only works when the structure is intact. HTML allows <dt> and <dd> as the direct children of a <dl>, or a set of <div> wrappers each holding one group. Anything else between them, a <p> or a <span> or a loose <li>, breaks the grouping.

What squirrel checks

One check, definition-list, at severity error. It reads the direct children of every <dl>.

• Fail when a direct child is anything other than <dt>, <dd> or <div>, or when a <div> child holds anything other than <dt> and <dd>. Report message: N definition list(s) with invalid structure. Each list is named dl#id, dl.class or bare dl, and every offending list is listed.
• Pass with N definition list(s) are properly structured.
• Info with No definition lists found.

The check reports the list, not the child, and stops at the first bad child in each one. It also inspects <div> wrappers one level deep, so a <div> containing another <div> is reported.

How to fix it

<dl>
  <div>
    <dt>Shipping</dt>
    <dd>Free over 50 EUR</dd>
  </div>
  <div>
    <dt>Returns</dt>
    <dd>30 days, no questions</dd>
  </div>
</dl>

Move anything that is not a term or a description outside the <dl>, or wrap each pair in a <div> and put your styling hooks there.

HTML also permits <script> and <template> as children of a <dl>. squirrel reports those, so a list with an inline template inside it is a false positive worth ignoring.

Enable / disable

Disable this rule

[rules]
disable = ["a11y/definition-list"]

Disable all Accessibility rules

[rules]
disable = ["a11y/*"]

Enable only this rule

[rules]
enable = ["a11y/definition-list"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• a11y/dlitem: <dt> and <dd> sitting outside a <dl> altogether.
• a11y/list-structure: the same check for <ul> and <ol>.
• a11y/listitem: orphaned <li> elements.
• a11y/table-headers: data tables with no <th> cells, the other way to present key-value data.

Accessibility findings ship in every audit next to the SEO, performance and agent experience rules. See Website security scan with AI for how an agent works through a report.

References

• The dl element, MDN
• The dl element, HTML Standard
• Understanding SC 1.3.1 Info and Relationships, W3C

Check your site

Run squirrel audit https://example.com and open the Accessibility section of the report. Each malformed list is listed by id or class. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.