# axe-core definition-list error dl element invalid dt dd nesting - how to fix it

## TL;DR

A [dl] may only contain dt elements followed by their dd elements (optionally wrapped in [div] for styling). A dd before its dt, a bare [p] or [span] as a direct child, or a dt with no dd breaks the association. Reorder so each dt comes before its dd, wrap groups in [div] if you need styling hooks, and remove any non-dt/dd/div direct children.

Description lists are underused on the modern web, which is why their markup rules are unfamiliar. Most glossary and spec content is built with [div] grids or tables instead. When you do use [dl], the payoff is real: screen readers announce the term-definition relationship explicitly. The rule's strictness about child order is what makes that announcement reliable.

The verbatim error looks like this:

```text
axe-core 4.x
Rule: definition-list (serious)
"Dl elements must only directly contain properly-ordered dt and dd groups, and script, template or div elements"

Element: [dl]
  [dd]First definition[/dd]
  [dt]Term[/dt]
  (dd appears before its dt)
```

## Steps

1. Reproduce with the single rule:

```bash
npx @axe-core/cli https://example.com/glossary --rules definition-list,dlitem
```

Expected: the malformed dl is listed.

2. Inspect the children of the flagged [dl]. Look for: dd before dt, text nodes or [span]/[p] as direct children, or dt elements with no following dd.

3. Repair the structure:

```html
[dl]
  [div]
    [dt]API key[/dt]
    [dd]A secret string that identifies your integration.[/dd]
  [/div]
  [div]
    [dt]Webhook[/dt]
    [dd]An HTTP callback fired on events.[/dd]
  [/div]
[/dl]
```

Each term (dt) precedes its definitions (dd); [div] wrappers are allowed.

4. Re-run the focused scan. Expected output: 0 violations for definition-list and dlitem.

5. Check with a screen reader that terms and definitions are announced as pairs.

6. Validate the rendered HTML, not your source. Template logic, CMS filters, and markdown renderers can all reorder or inject elements between your dt and dd. View source on the rendered page and check the actual child sequence of each [dl].

7. If your content does not fit the term-definition model (for example, a two-column layout of unrelated facts), do not force it into a [dl]. Use a [table] with headers or a list. Misusing [dl] for layout creates the violations this rule reports.
## When to use

- Axe flags definition-list or dlitem on a description list.
- A glossary, FAQ, or spec table built with dl renders with terms and definitions out of order.
- A CMS rich-text field emits dl markup with stray paragraphs inside.

## When not to use

- The list is a ul/ol with bad nesting (that is the list rule).
- The content is tabular data (use a real [table] with th/scope instead of faking it with dl).
- The dl is generated by markdown and you cannot control the output (switch the renderer or post-process the HTML).

## Why it happens

Assistive tech announces dt/dd as term-definition pairs, which is what makes a glossary navigable. When the order is wrong or stray elements sit between them, the pairing breaks and definitions get announced under the wrong term or as loose text. The [div]-wrapper allowance exists precisely so styling never has to break the semantics.

The HTML spec tightened [dl] content rules over the years: the [div] wrapper allowance was added so authors could style term-definition groups without breaking semantics. Older references and older axe versions describe slightly different allowed children, which is why code copied from old tutorials fails the current rule. The current rule permits dt, dd, div, script, and template as direct children, in term-before-definition order.

## Edge cases

- A dt with multiple dd elements is valid (one term, several definitions). A dd with no preceding dt is not.
- script and template elements are allowed as direct children; anything else visible is not.
- Markdown renderers that emit [dl] from definition syntax sometimes produce invalid nesting. Validate the rendered HTML, not the markdown source.
- Nested dl elements are legal but rare; keep each level's dt/dd ordering correct independently.
- Microdata and RDFa attributes on dt/dd are fine; the rule only checks element types and order.
- A [dl] with a single dt and no dd is valid per the rule but pointless. Add the definition or drop the list.
- Description lists inside [figure] with [figcaption] are a legitimate pattern for annotated data.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qpuC62e6TiYuptmamYBYqQ