# List row

> One tappable line in a list. The whole row is the target; a value or a single ⋯ sits beside it, outside the pressed area.

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

## Usage

### What it is
The one list row in Kwark (`components/ui/ListRow.tsx`): the cast, locations, projects on a phone, crew. Pressing anywhere on the row opens the record. It has no buttons inside it. If the record has actions, one ⋯ button sits after the row, outside the pressed area, and opens them (a [sheet](https://kwark.space/designSystem/components/sheet.md) on a phone).

### The parts
| Part | Holds | Example |
|---|---|---|
| Lead | A cover, an avatar or a 20px icon | Mira's initials in her colour; the project's mini poster |
| Title | The name | *Mira Rao* |
| Meta | One quiet line of what matters next | *Lead · played by Tara Sen* |
| Value | One figure, tabular | *41 scenes* |
| Trail | A chevron (it goes somewhere), or one ⋯ (it has actions) | |

### When to use
- Any list of records where each opens its own page, especially on a phone.

### When not to use
- When people compare columns: a [data table](https://kwark.space/designSystem/components/data-table.md).
- For cards people arrange by hand: [index cards](https://kwark.space/designSystem/components/index-card.md) on the board.
- For commands: a [menu](https://kwark.space/designSystem/components/menu.md).

### Writing the meta line
Say what someone needs before opening it, in the order they need it: role, then who plays them; the format, then the revision, then when it was last edited. Two or three facts, joined with a middle dot. Never a sentence.

## Style

### Anatomy

1. **Row** (`.k-row`): a flex line, at least 56px (72px with a lead, `.has-lead`), 1px `--k-line` under it.
2. **Main** (`.k-row__main`): the pressed area, 8px 16px, 12px gap; a `button` or `a` when it opens something, a `div` when static. Hover `--k-raise`; pressed 8% `--k-text` into it.
3. **Lead**: a 40px avatar, a 36 × 54px cover in `--k-cover-bg`, or a 20px icon in `--k-text-2`.
4. **Title**: Raleway 600 16px, one line, ellipsis.
5. **Meta**: Poppins 400 12px `--k-text-2`, one line, ellipsis, tabular figures.
6. **Value**: Poppins 500 12px tabular `--k-text-2`, inside the main area.
7. **Chevron**: 16px, inside the main area when the row goes somewhere.
8. **Trail** (`.k-row__trail`): outside the main area, 8px right padding; one 36px ⋯ (44px on touch).
9. **Static row**: no hover, no chevron; read-only records say so in the meta (*read only*).

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-cover-bg` | #22211f |  |
| `--k-cover-ink` | #eee7db |  |
| `--k-tap` | 44px |  |
| `--k-radius-control` | 6px |  |
| `--k-fs-title` | 16px |  |
| `--k-fs-meta` | 12px |  |
| `--k-font-display` | 'Raleway', 'Poppins', system-ui, sans-serif |  |
| `--k-icon-md` | 16px |  |
| `--k-icon-lg` | 20px |  |

## Code

### React

In the Kwark app: `import { ListRow } from '@/components/ui/ListRow'`.

```tsx
<ListRow title="Mira Rao" meta="Lead · played by Tara Sen"
  leading={<UserAvatar user={mira} size="lg" />}
  trailing={<DropdownMenu label="Actions for Mira Rao" trigger={<MoreHorizontal size={16} />} triggerClassName="k-iconbtn" items={items} />}
  onClick={() => openCharacter(mira.id)} />
```

| Prop | Type | Notes |
|---|---|---|
| `title` | `string` | The record’s name; one line, truncates. |
| `meta` | `ReactNode` | One quiet supporting line. |
| `leading` | `ReactNode` | A cover, avatar or icon; the row grows to 72px. |
| `trailing` | `ReactNode` | A value, chevron or one ⋯ button, outside the pressed area. |
| `onClick` | `() => void` | Makes the main area a button. Without it the row is static. |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-lrow-list" aria-label="Cast">
  <div class="kw-lrow has-lead"><button class="kw-lrow__main" type="button"><span class="kw-lrow__lead"><span class="kw-avatar kw-avatar--lg" style="--kw-peer:var(--k-series-1)">MR</span></span><span class="kw-lrow__text"><span class="kw-lrow__title">Mira Rao</span><span class="kw-lrow__meta">Lead · played by Tara Sen</span></span><span class="kw-lrow__value">41 scenes</span></button><span class="kw-lrow__trail"><button class="kw-icon-button" type="button" aria-label="Actions for Mira Rao" aria-haspopup="menu"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><circle cx="5" cy="12" r="1.8"/><circle cx="12" cy="12" r="1.8"/><circle cx="19" cy="12" r="1.8"/></svg></button></span></div>
  <div class="kw-lrow has-lead"><button class="kw-lrow__main" type="button"><span class="kw-lrow__lead"><span class="kw-avatar kw-avatar--lg" style="--kw-peer:var(--k-series-4)">NA</span></span><span class="kw-lrow__text"><span class="kw-lrow__title">Nana (Vithal Rao)</span><span class="kw-lrow__meta">Supporting · not cast yet</span></span><span class="kw-lrow__value">12 scenes</span></button><span class="kw-lrow__trail"><button class="kw-icon-button" type="button" aria-label="Actions for Nana" aria-haspopup="menu"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><circle cx="5" cy="12" r="1.8"/><circle cx="12" cy="12" r="1.8"/><circle cx="19" cy="12" r="1.8"/></svg></button></span></div>
</div>
<div class="kw-lrow-list" aria-label="Projects">
  <div class="kw-lrow has-lead"><a class="kw-lrow__main" href="#blank-pages"><span class="kw-lrow__lead"><span class="kw-lrow__cover" aria-hidden="true">BP</span></span><span class="kw-lrow__text"><span class="kw-lrow__title">Blank Pages</span><span class="kw-lrow__meta">Feature film · Pink revision · edited 14:05</span></span><svg class="kw-lrow__chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6"/></svg></a></div>
</div>
<div class="kw-lrow-list" aria-label="Locations">
  <div class="kw-lrow"><button class="kw-lrow__main" type="button"><span class="kw-lrow__lead"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 21s-7-6.2-7-11.5a7 7 0 0 1 14 0C19 14.8 12 21 12 21z"/><circle cx="12" cy="9.5" r="2.5"/></svg></span><span class="kw-lrow__text"><span class="kw-lrow__title">Studio 2, Andheri</span><span class="kw-lrow__meta">Scenes 12, 12A, 31 · Days 7 and 8</span></span><svg class="kw-lrow__chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6"/></svg></button></div>
  <div class="kw-lrow"><div class="kw-lrow__main"><span class="kw-lrow__lead"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 21s-7-6.2-7-11.5a7 7 0 0 1 14 0C19 14.8 12 21 12 21z"/><circle cx="12" cy="9.5" r="2.5"/></svg></span><span class="kw-lrow__text"><span class="kw-lrow__title">Rooftop, Bandra</span><span class="kw-lrow__meta">Recce on Day 3 · read only</span></span></div></div>
</div>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | The row's main area, then its ⋯ (two stops per row with actions, one without). |
| Enter (link) / Enter or Space (button) | Opens the record. |
| Enter / Space on ⋯ | Opens the actions menu; Escape returns to ⋯. |

### ARIA
- The main area is one `button` or `a`; its accessible name is its text in order: *Mira Rao, Lead, played by Tara Sen, 41 scenes*.
- The ⋯ is named with its object: *Actions for Mira Rao*. Never just *More*.
- A list of rows sits in a named container (`aria-label="Cast"`) or under a heading.
- Focus: a 2px `--k-focus` ring inset by 2px with 6px corners, so neighbouring rows never clip it.

### Moving older code over
The core specimen used to put the chevron and trail inside one big button. `ListRow.tsx` keeps the trail outside `.k-row__main`; follow the component.

## For agents

### Rules

- **Never** put buttons inside a list row's pressed area; one ⋯ may sit after it, named with its object.
- **Must** make the whole main area one link or button, at least 56px tall (72px with a lead).
- **Must** keep the meta line to one line of two or three facts joined with a middle dot.
- **Always** use the chevron only when the row goes somewhere, and the ⋯ only when it has actions.
- **Must** open row actions in a sheet on phones.

### AI readiness test

**Task:** List the locations of Blank Pages on a phone.

**Give the agent:** This page, Location card, Phones pattern.

**Constraint:** Each location has scenes, shooting days and actions (rename, merge, delete).

**A reliable answer:**
- ListRow per location with a pin icon
- Meta "Scenes 12, 12A, 31 · Days 7 and 8"
- Actions in one ⋯ named "Actions for Studio 2, Andheri" outside the row
- A sheet on tap of ⋯
- No inline buttons
