# Description list

> Labelled facts about one thing, read like a camera report: roll, scene, take, lens, stop, timecode. Label left, value right in tabular figures; stacked in narrow panels.

Source: https://kwark.space/designSystem/components/description-list

## Usage

### What it is
A description list is the facts of one thing: a label and its value, row after row. Kwark's model is the **camera report** a 2nd AC fills for every take, and the details of an event opened in the calendar: short labels, exact values, nothing to edit in place.

### When to use
- One item's facts in a panel, drawer, inspector or sheet: a take, a camera setup, a location candidate, a calendar event.
- When values are short and exact: *T2.8*, *01:04:12:07*, *₹45,000*.

### When not to
- Many items with the same facts. Use a [Data table](https://kwark.space/designSystem/components/data-table.md).
- Editable fields. Use labelled inputs; a description list is for reading.
- Two or three facts that fit in a sentence: *Roll A007, Camera A*.

### Variants
| Variant | Use |
|---|---|
| Side by side (default) | Label column sized to the longest label, at least 88px |
| Ruled (`--ruled`) | Hairlines between rows, for reports and anything printed |
| Stacked (`--stacked`) | Label above value, for drawers 320px wide and phones |

### Writing
- Labels are short nouns in the department's own words (*Stop*, not *Aperture value*).
- Units with every value: *40 mm*, *24 fps*.
- Empty values say *Not set*, in quiet text. Never an empty gap or a dash alone.

**Do:** *Stop* · *T2.8*, *Timecode in* · *01:04:12:07*, *Filter* · *Not set*.

**Don't:** *Aperture value:* *2.8* with no unit, and a blank row where the filter should be.

## Style

### Anatomy

1. **Grid**: `minmax(88px, max-content) 1fr`, 8px × 20px gaps.
2. **Label** (`dt`): 12px `--k-text-2`, top-aligned with the value's first line.
3. **Value** (`dd`): 13.5px/1.55 `--k-text`; figures tabular; wraps, never truncates.
4. **Ruled**: 1px `--k-line` between rows, 8px padding.
5. **Empty** (`data-empty`): `--k-text-2`.
6. **Report head** (`.kw-facts__head`): a 36px slate tile with scene and take, the title 14px 500, the roll line 12px, and a *Circled* tag in mint.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-chart-mint` | #779a8b | var(--k-brand-mint) |
| `--k-fs-meta` | 12px |  |
| `--k-fs-notes` | 13.5px |  |
| `--k-radius-card` | 10px |  |

### States
| State | Look |
|---|---|
| Value | `--k-text` |
| Not set | `--k-text-2` |
| Long value | Wraps under itself, the label stays at the top |
| Narrow (< 360px) | Use `--stacked`; 12px between pairs |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<section class="kw-facts" aria-label="Scene 12, take 3">
  <header class="kw-facts__head"><span class="kw-facts__slate"><b>12</b><i>3</i></span><span><strong>Scene 12 · Take 3</strong><small>Roll A007 · Camera A · Sat 23 Nov</small></span><span class="kw-facts__circled">Circled</span></header>
  <dl class="kw-dl kw-dl--ruled">
    <dt>Lens</dt><dd class="kw-num-tab">40 mm</dd>
    <dt>Stop</dt><dd class="kw-num-tab">T2.8</dd>
    <dt>Frame rate</dt><dd class="kw-num-tab">24 fps · shutter 180°</dd>
    <dt>Timecode in</dt><dd class="kw-num-tab">01:04:12:07</dd>
    <dt>Sound roll</dt><dd class="kw-num-tab">S004</dd>
    <dt>Filter</dt><dd data-empty>Not set</dd>
    <dt>Note</dt><dd>Hold on the doorway after she leaves. The monitor flare is wanted.</dd>
  </dl>
</section>
<div class="kw-facts kw-facts--narrow">
  <dl class="kw-dl kw-dl--stacked">
    <dt>Location</dt><dd>Old Film Lab rooftop, Andheri East</dd>
    <dt>Cost per day</dt><dd class="kw-num-tab">₹45,000</dd>
    <dt>Contact</dt><dd>Location manager, Sana K.</dd>
    <dt>Night permit</dt><dd data-empty>Not set</dd>
  </dl>
</div>
```

### Markup
`<dl class="kw-dl kw-dl--ruled">` with `dt`/`dd` pairs. Put `data-empty` on a `dd` that says *Not set*. Add `.kw-num-tab` to values with figures so columns of reports line up.

## Accessibility

### Screen readers
`<dl>`, `<dt>` and `<dd>` are announced as terms and definitions. Do not use a table for one item's facts.

### Keyboard
Not interactive. Copyable values (timecode) get their own copy button outside the list.

## For agents

### Rules

- **Must** use `<dl>` for one item's facts.
- **Always** show "Not set" for an empty value.
- **Must** give every figure its unit and use tabular figures.
- **Always** use the stacked variant under 360px.

### AI readiness test

**Task:** Show a location candidate's details in a 320px drawer.

**Give the agent:** Description list, Location card, Drawer.

**Constraint:** The night permit is not known yet.

**A reliable answer:**
- Stacked variant
- Labels as short nouns
- Cost with currency in tabular figures
- Night permit reads Not set
- Contact by role
