DescriptionList

Role and semantics

• The root is a native <dl>. Screen readers take the term and definition relationship from these elements; no extra ARIA role is needed.
• Each row is a <div> that wraps the <dt> and <dd> elements. HTML allows this wrapper inside <dl>.
• The action sits in a separate <dd> at the end of the row, so no control sits in the <dl> outside a <dd>. Screen readers read the action as a second definition of the same term.
• For an empty value — is visual (aria-hidden) and the reason (“no information”) is read to screen readers.
• Terms and values are in DOM order; the layout changes only through the CSS grid.

Keyboard

Key	Behaviour
Tab	DescriptionList takes no focus. The actions in the rows take focus in visual order.
Enter, Space	Runs the focused action (Button behaviour).

Focus

DescriptionList has no focus ring of its own. An action control carries its own ring: 2 px wide and 2 px away.

Screen reader output

Example	Read
Term and value	“Status”, “Active” (as term and definition)
Empty value	“Description”, “no information”
Row with an action	“Identifier”, “ITEM-1024”, “Copy, button”

Replace the word with emptyLabel; the default is a library string. When a page has several actions, each name should say what it affects (“Copy identifier”).

Contrast

Text is at least 4.5:1 in every brand and mode; values are computed from the bigbang and fixture token output.

Pair	Light mode	Dark mode
color-text-default / color-surface-default	16.16:1	17.18:1
color-text-subtle / color-surface-default	8.77:1	10.27:1
color-text-subtle / color-surface-raised (inside a Card)	9.07:1	9.23:1

The divider line (color-border-subtle, 1.22:1) is decorative: rows are also separated by spacing and the line carries no information (WCAG 1.4.11 does not require it).

WCAG 2.2

Criterion	How DescriptionList meets it	What the product team does
1.3.1 Info and relationships	Native dl, dt, dd; rows are grouped with div.	Keep a term and its value in one row; do not separate the term from the value.
1.3.2 Meaningful sequence	The layout changes with CSS; the DOM order is term, value, action.	Keep this order when you write rows with parts.
1.4.3 Contrast	Text is at least 8.77:1.	Do not pass custom colours.
1.4.10 Reflow	Stacks below 1024 px; a long value wraps.	Do not truncate values.
2.4.6 Headings and labels	Terms must be short and descriptive.	Write the term so it describes the value.
2.5.8 Target size	The action is a Button; sm is 32 px.	Keep a target of at least 24 px for the action.