# Flux 2.0 — Description list

Labelled values in a row or a stack. The summary block at the top of a record.

Reference: https://flux.kaptio.com/components/description-list/
Requires: https://flux.kaptio.com/tokens/v2/flux.css and flux-components.css

## Use it when
Presents the fixed attributes of one object — a booking’s traveller, departure, nights and total — as label and value pairs. This is the most common block in a Kaptio operations screen, and the one most often rebuilt from scratch. Use it so that every record header in every product reads the same way.

## Do not use it when
Not for tabular data. If you have the same attributes across many objects, that is a table, and a reader needs to compare down a column. A description list describes exactly one thing.

## Markup

### Default

<dl class="flux-dl">
  <div class="flux-dl__pair">
    <dt class="flux-dl__term">Traveller</dt>
    <dd class="flux-dl__detail">Marianne Hollis</dd>
  </div>
  <div class="flux-dl__pair">
    <dt class="flux-dl__term">Departure</dt>
    <dd class="flux-dl__detail flux-dl__detail--data">14 March 2027</dd>
  </div>
  <div class="flux-dl__pair">
    <dt class="flux-dl__term">Nights</dt>
    <dd class="flux-dl__detail flux-dl__detail--data">11</dd>
  </div>
  <div class="flux-dl__pair">
    <dt class="flux-dl__term">Total</dt>
    <dd class="flux-dl__detail flux-dl__detail--data">EUR 8,420.00</dd>
  </div>
</dl>

### In a card

<div class="flux-card">
  <dl class="flux-dl">
    <div class="flux-dl__pair">
      <dt class="flux-dl__term">Reference</dt>
      <dd class="flux-dl__detail flux-dl__detail--data">KB-104928</dd>
    </div>
    <div class="flux-dl__pair">
      <dt class="flux-dl__term">Status</dt>
      <dd class="flux-dl__detail"><span class="flux-badge flux-badge--confirmed">Confirmed</span></dd>
    </div>
    <div class="flux-dl__pair">
      <dt class="flux-dl__term">Balance due</dt>
      <dd class="flux-dl__detail flux-dl__detail--data">13 January 2027</dd>
    </div>
  </dl>
</div>

### Stacked

<dl class="flux-dl flux-dl--stacked">
  <div class="flux-dl__pair">
    <dt class="flux-dl__term">Subtotal</dt>
    <dd class="flux-dl__detail flux-dl__detail--data">EUR 7,890.00</dd>
  </div>
  <div class="flux-dl__pair">
    <dt class="flux-dl__term">Service fee</dt>
    <dd class="flux-dl__detail flux-dl__detail--data">EUR 530.00</dd>
  </div>
  <div class="flux-dl__pair">
    <dt class="flux-dl__term">Total</dt>
    <dd class="flux-dl__detail flux-dl__detail--data">EUR 8,420.00</dd>
  </div>
</dl>

## API
- flux-dl (class): The list. Horizontal, wrapping.
- flux-dl--stacked (class): Label left, value right, one pair per line.
- flux-dl__pair (class): Wraps one dt and dd. Required — dl children cannot be laid out directly.
- flux-dl__term (class): The label.
- flux-dl__detail (class): The value.
- flux-dl__detail--data (class): Mono with tabular figures. For references, dates, counts and money.

## Accessibility
- Use dl, dt and dd. A grid of divs conveys no relationship, so a screen reader reads eight unconnected strings instead of four labelled values.
- Each dt needs exactly one dd. If a value is genuinely absent, say so — an em dash or "Not set" — rather than leaving the dd empty.
- The wrapping div between dl and its pairs is valid HTML and does not break the association.
- Do not use a description list to fake a two-column table. A reader navigating a table expects row and column semantics that a dl does not provide.

## Keyboard
- —: Not interactive. Any control inside a value keeps its own behaviour.

## Tokens
- --flux-dl-gap-x
- --flux-dl-gap-y
- --flux-dl-term-gap
- --flux-dl-term-color
- --flux-dl-term-size
- --flux-dl-detail-color
- --flux-dl-detail-size

## Do
- Put the value in mono when it is data a reader will compare, copy or quote.
- Keep labels to one or two words so the pairs align down a wrapped row.
- Order the pairs by what the reader looks for first, not by what the database returns first.

## Do not
- Do not put a person’s or place’s name in mono. Mono is for data, not language.
- Do not add vertical rules between pairs. The gap is the separator.
- Do not use it for more than one object.