# List

Stacks items of one kind in rows that a reader scans, opens or chooses from.

* Kind: component
* Page: https://design.werklist.com/components/list
* Version: 2.1.2

## When to use it

* Items that each open a page, such as the modules of a workspace or the stages of a job.
* Settings with a switch per row, such as who on a hiring team can send offers.
* A short set of options to choose from, such as the status of a work permit.

## When not to use it

* Rows that share compared columns: use the board grid or the report table.
* Nested items: use the tree of the side navigation.
* Images or items of very different sizes: use Card.

## Rules

* Permitted: an item that is coming says Soon in words.
* Permitted: rows separated by space and a hover fill.
* Not permitted: a row faded by opacity to show it is unavailable.
* Not permitted: lines between the rows of a short list.

## Anatomy

* Grouped card: corner radius 24 px, padding 6 px, rows 2 px apart (--surface-1, --radius-3xl)
* Row in a grouped card: padding 12 px, corner radius 18 px, 46.5 px high; text in Subtitle, 15 px, medium, on a line of 22.5 px; gap 14 px (--space-3, --type-product-subtitle)
* Row in a plain list: padding 8 px, corner radius 8 px, 36 px high under a mouse and 44 px on coarse pointers; text in Body, 14 px on 20 px, medium; gap 10 px (--radius-lg, --space-2, --type-product-body)
* Row, two lines: 58 px in a card (10 px above and below, 20 px and 18 px lines), 50 px on a panel
* Leading element: icon 20 px, avatar 32 px or checkbox 16 px; --text-muted, --text on the current row
* Second line: Dense, 13 px on 18 px (--type-product-dense, --text-muted)
* Trailing element: chevron 18 px in a card and 16 px on a panel, a Switch, a Counter, or a short value in Dense, 13 px, tabular (--text-muted)
* Group heading: Dense, 13 px on 18 px, medium, 8 px above and below; stays at the top while its group scrolls, on a frosted fill of --surface-1 (--type-product-dense, --text-label)

## Sizes

* grouped: height 46.5 px, 58 px with two lines, padding 12 px, type Subtitle, 15 px, medium
* plain: height 36 px under a mouse, 44 px on coarse pointers, padding 8 px, type Body, 14 px on 20 px, medium

## States

* hover: faint fill; fine pointer only (--glass-fill-hover)
* pressed: the same faint fill; a link row in a grouped card scales to 0.985 (--glass-fill-hover)
* current: tinted fill in --text, aria-current page; the other rows of the list turn --text-muted (--nav-fill-active, --text-muted)
* chosen: 16 px tick at the end, aria-selected true; multiple choice uses a leading Checkbox (--brand-blue)
* focus visible: 2 px ring inside the row, offset minus 2 px (--focus-ring)
* soon: the word Soon as the trailing value; not a link, aria-disabled true, not faded (--text-muted)

## Keyboard

* Tab: Moves between links in a list of links; enters a list you choose from
* Up and Down: Move between rows of a listbox
* Home and End: First and last row
* Space: Chooses or clears the focused row
* Enter: Opens the focused row
* Right: Moves into the row's own buttons
* Left or Escape: Returns to the row

## Accessibility

* ul and li for a list of links; listbox and option for choosing; not grid.
* The accessible name of a row holds its full text.
* When the focused row is removed, focus moves to the next row, or the previous one at the end.
* Current and chosen rows keep an outline or a tick in forced colors.

## Content

* Rows are parallel and of similar length.
* No end punctuation unless each row is a full sentence.
* Titles wrap to two lines, then an ellipsis; file names are cut in the middle.

## Tokens

* --type-product-subtitle
* --type-product-body
* --type-product-dense
* --glass-fill-hover
* --nav-fill-active
* --brand-blue
* --text
* --text-muted
* --text-label
* --surface-1
* --radius-lg
* --radius-3xl
* --space-2
* --space-3
* --focus-ring