Deflist
Typography styling for native <dl>, <dt>, <dd> elements, sitting alongside other classless typography element selectors (headings, body text, lists) shipped under src/foundation/typography/. With no orientation value the layout is a two-column grid that collapses to stacked on narrow viewports, with divider lines between rows and support for multiple <dd> per <dt>. This is the right element for key-value pairs, not tables - tables are for tabular data with multiple columns and headers.
Usage
When to use
- Key-value metadata displays (mission metadata, crew listings, product specs)
- CMS field lists where the field formatter emits
<dl>,<dt>,<dd>out of the box - Any pair-oriented content that is not tabular
When not to use
- Tabular data with multiple columns - use
<table> - A single pair - use inline text with
<strong>or a heading - Navigation or lists of links - use
<ul>
Do
- Use real
<dl>,<dt>,<dd>elements so assistive tech recognizes the relationship - Group consecutive
<dd>siblings under one<dt>when a term has multiple values - Rely on the responsive grid - no extra classes needed
Don't
- Don't wrap
<dt>/<dd>pairs in extra<div>s - they break the implicit grouping - Don't use
<dl>as a generic two-column layout primitive - Don't add striped row backgrounds - dividers are clearer for key-value lists
Choosing an orientation
The 3 layouts are separate states rather than one behaviour with a breakpoint:
- No orientation value - two columns from 768px up, stacked below it. This is what a bare
<dl>renders, and it suits body copy that has the full page width to work with. horizontal- two columns at every width. Reach for it when the terms are short enough to hold their own column on a phone.vertical- stacked at every width. Reach for it inside a narrow container, where a term column would leave the details too little room to read.
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | array | - | Array of {term, details} objects where term is the label string and details is an array of detail strings (each rendered as a sibling <dd>). |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.horizontal | Orientation | Yes | Children flow along the horizontal axis. |
.vertical | Orientation | - | Children flow along the vertical axis. |
Examples
Single pair
One term with one detail.
Multiple details per term
One <dt> followed by multiple <dd> siblings (e.g. crew listing).
Long wrapping values
Long value text that wraps across multiple lines in the detail column.
Orientations
horizontal holds the two columns and vertical stacks the pair, both at every width.
Responsive layout
The bare form, carrying no orientation value: two columns from 768px up, stacked below it. Resize the canvas to watch it collapse.
Dividers
Horizontal rule between each row pair.
Accessibility
- WCAG 2.2 AA
- Semantic
<dl>,<dt>,<dd>- assistive tech recognizes the relationship automatically - No ARIA needed
- Grid layout uses
display: gridon the<dl>- screen readers still announce it as a description list (CSSdisplaydoes not change semantic role).
Related
- Typography - heading, body text, and list classless counterparts
- code - another classless typography component