Description List

Display key-value pairs using semantic HTML description lists. Perfect for detail panels, settings displays, and profile information.

Overview

Description lists provide a structured way to present pairs of labels and values. Using the semantic <dl>, <dt>, and <dd> elements ensures proper accessibility and document structure while providing flexibility for visual styling.

Key features:

Semantic HTML for accessibility and SEO
Flexible layouts: vertical stacking or horizontal rows
Grouped sections for organized data presentation
Consistent styling with muted labels and clear values
Responsive design that adapts to screen size
Uses @scope for encapsulated, semantic CSS selectors

Simple Vertical Layout

A basic vertical description list with terms stacked above their descriptions. The <dl-item> custom element groups each <dt>/<dd> pair.

<dl class="key-value" data-layout="stacked"> <dl-item> <dt>Full Name</dt> <dd>Alexandra Chen</dd> </dl-item> <dl-item> <dt>Email Address</dt> <dd>alexandra.chen@example.com</dd> </dl-item> <dl-item> <dt>Phone Number</dt> <dd>+1 (555) 123-4567</dd> </dl-item> <dl-item> <dt>Status</dt> <dd> <span class="badge success">Active</span> </dd> </dl-item> </dl>

Stacked Layout Styles

@scope (.key-value[data-layout="stacked"]) { :scope { margin: 0; display: flex; flex-direction: column; gap: var(--size-l); } dl-item { display: flex; flex-direction: column; gap: var(--size-2xs); } dt { font-size: var(--font-size-sm); color: var(--color-text-muted); } dd { margin: 0; font-size: var(--font-size-md); } }

Horizontal Layout

A horizontal layout with labels on the left and values on the right. This format works well for detail panels, settings pages, and profile information where you want to scan labels quickly.

<dl class="key-value"> <dl-item> <dt>Full Name</dt> <dd>Alexandra Chen</dd> </dl-item> <dl-item> <dt>Email</dt> <dd>alexandra.chen@example.com</dd> </dl-item> <dl-item> <dt>Phone</dt> <dd>+1 (555) 123-4567</dd> </dl-item> <dl-item> <dt>Status</dt> <dd> <span class="badge success">Active</span> </dd> </dl-item> </dl>

Horizontal Layout Styles

@scope (.key-value) { :scope { margin: 0; } dl-item { display: grid; grid-template-columns: 140px 1fr; gap: var(--size-m); align-items: baseline; padding-block: var(--size-s); border-bottom: 1px solid var(--color-border); } dl-item:last-child { border-bottom: none; } dt { font-size: var(--font-size-sm); color: var(--color-text-muted); } dd { margin: 0; } } /* Responsive: stack on small screens */ @media (max-width: 480px) { @scope (.key-value) { dl-item { grid-template-columns: 1fr; gap: var(--size-2xs); } } }

Grouped Sections

Multiple description lists organized into logical sections with headings. Each section uses a <layout-card> for visual separation. Ideal for profile pages, order details, or settings displays.

<layout-stack data-layout-gap="l">  <layout-card data-padding="l"> <layout-stack data-layout-gap="m"> <h2 class="section-heading">Personal Information</h2> <dl class="key-value"> <dl-item> <dt>Full Name</dt> <dd>Alexandra Chen</dd> </dl-item> <dl-item> <dt>Date of Birth</dt> <dd>March 15, 1992</dd> </dl-item> </dl> </layout-stack> </layout-card>  <layout-card data-padding="l"> <layout-stack data-layout-gap="m"> <h2 class="section-heading">Contact Details</h2> <dl class="key-value"> <dl-item> <dt>Email</dt> <dd>alexandra.chen@example.com</dd> </dl-item> <dl-item> <dt>Phone</dt> <dd>+1 (555) 123-4567</dd> </dl-item> </dl> </layout-stack> </layout-card> </layout-stack>

Section Heading Styles

.section-heading { margin: 0; font-size: var(--font-size-md); font-weight: var(--font-weight-semibold); }

Configuration

Description list patterns use these elements and CSS techniques:

HTML Structure

Element	Purpose	Description
`<dl class="key-value">`	Container	The description list container. Add `data-layout="stacked"` for vertical layout.
`<dl-item>`	Row grouping	Custom element that groups a `<dt>`/`<dd>` pair for styling.
`<dt>`	Label	The description term (label).
`<dd>`	Value	The description details (value).

Grid Row Widths

Label Width	Best For	Description
`100px`	Short labels	Works well for single-word labels like "Name", "Email", "Phone"
`140px`	Medium labels	Good balance for labels like "Full Name", "Phone Number"
`180px`	Long labels	Accommodates longer labels like "Email Address", "Member Since"

CSS Custom Properties

Property	Usage	Description
`--color-text-muted`	Labels (dt)	Subdued color for term labels to create visual hierarchy
`--color-border`	Row separators	Light border color for horizontal row dividers
`--font-size-sm`	Labels (dt)	Smaller font size for term labels

Usage Notes

Semantic HTML: Always use <dl>, <dt>, and <dd> elements for proper accessibility. Screen readers announce these as description lists.
CSS @scope: Styles use @scope (.key-value) to encapsulate rules and enable semantic element selectors (dl-item, dt, dd) without class pollution.
Item grouping: The <dl-item> custom element groups each term/description pair. This is valid HTML5 and enables grid layout for horizontal display.
Multiple values: A single <dt> can have multiple <dd> elements for multiple values (e.g., multiple phone numbers).
Responsive design: The horizontal layout uses a media query to stack on smaller screens, switching from grid to single-column display.
Value formatting: Use badges, icons, or formatted text in <dd> elements to enhance readability.
Empty values: Display a dash or "Not provided" for empty values rather than leaving blank.
Long values: For long text values, consider truncation with a "show more" toggle or allowing text to wrap naturally.
Actions: You can include edit links or buttons within <dd> elements for inline editing capabilities.