Structuring Key-Value Metadata with HTML Description Lists

Web applications routinely present key-value pairs: invoice summaries, user profiles, technical specifications, and glossary terms. All too often, these are constructed using generic <div> soup or non-semantic <ul> lists, depriving screen readers and search bots of the contextual relationship between the term and its corresponding definition.

The HTML <dl> (Description List) element, together with <dt> (Description Term) and <dd> (Description Details), provides the precise semantic markup for association lists.

Example #

Structuring a user profile or server specification cleanly:

<dl class="spec-grid">
  <dt>Runtime</dt>
  <dd>Node.js 22 LTS</dd>

  <dt>Region</dt>
  <dd>Frankfurt, Germany (eu-central-1)</dd>

  <dt>Uptime SLA</dt>
  <dd>99.99%</dd>
</dl>

Implementation #

With modern CSS Grid, a single <dl> can be formatted into clean side-by-side or tabular layouts without needing redundant wrapper <div>s:

.spec-grid {
  display: grid;
  grid-template-columns: 140px 1fr;
  gap: 12px 20px;
  margin: 0;
  padding: 20px;
  border: 1px solid var(--lightgray);
  border-radius: 8px;
}

.spec-grid dt {
  font-weight: 700;
  color: var(--blue);
}

.spec-grid dd {
  margin: 0;
  color: var(--darkgray);
}

Main Point: Use <dl>, <dt>, and <dd> for key-value associations to deliver accessible, machine-readable specifications without compromising visual design.

Credits #

Photo by Dan Freeman on Unsplash

← Home