List

A list stacks items of one kind, one per row, so a reader can scan them and act on one. Each row stands on its own and shares no columns with the rows around it.

What it is

Modules

Can send offers

Ana HorvatRecruiter, Zagreb
Marko BabićAccount manager, Split

Welders for Split

When to use it

Use a list for items of one kind that a reader opens, switches on or picks, such as the modules of a workspace, the people on a hiring team or the stages of a job.

When rows share columns that a reader compares, use the board grid or a report table. When items hold other items, use the tree of the side navigation. When items are pictures, or vary a lot in size, use cards.

Anatomy

A row has an optional leading element (an icon, an avatar or a checkbox), the text, and an optional trailing element (a chevron, a switch, a counter or a short value).

Ana HorvatRecruiter, Zagreb

Card: Corner radius 24 px, padding 6 px; --radius-3xl
Row in a card: Padding 12 px, corner radius 18 px; --space-3
Text in a card: Subtitle, 15 px, medium; --type-product-subtitle
Row on a panel: 36 px high, 44 px on touch, corner radius 8 px; --radius-lg
Text on a panel: Body, 14 px, medium; --type-product-body
Row with two lines: 58 px in a card
Space between rows: 2 px
Leading icon or avatar: 20 px or 32 px
Space after the leading element: 14 px in a card, 10 px on a panel
Second line: Dense, 13 px, in muted ink; --type-product-dense
Chevron: 18 px in a card, 16 px on a panel; --text-muted

States

In a list that navigates, the current row keeps a tinted fill and the full ink, and the rows around it turn muted.

A module that is coming soon stays in the list with the word Soon at the end of its row. The row is not a link, and it is not faded: the word says the state.

Rest
- Candidates
Hover
- Candidates
Current
- Candidates
Focus
- Candidates
Soon
- CandidatesSoon

Under the pointer: Faint fill, mouse only; --glass-fill-hover
Pressed: The same fill; a row in a card sinks to 98.5 percent; --glass-fill-hover
Current row: Tinted fill in full ink, the other rows muted; --nav-fill-active
Chosen row: 16 px tick at the end; --brand-blue
Focus ring: 2 px, inside the row; --focus-ring

Keyboard and screen readers

A list of links follows the browser's own Tab order. A list you choose from takes one Tab stop, and the arrow keys move inside it. When the focused row is removed, focus moves to the next row, or to the previous one at the end.

Up and Down: Move between rows
Home and End: First and last row
Space: Chooses or clears a row
Enter: Opens the row
Right: Into the row's own buttons
Left or Escape: Back to the row

Long, empty and loading

When a list runs longer than the screen, give it group headings that stay at the top while their group scrolls past. They are set in Dense, on a frosted fill.

A list with no rows shows the empty state in its place: one sentence and the next action. While rows load, skeleton rows of the same height hold the space.

A title wraps to two lines and then ends with an ellipsis, and the second line stays on one line. File names are cut in the middle so the extension stays visible. The row's accessible name holds the full text.

Permitted and not permitted

Permitted

A row for a module that is coming, with the word Soon.
Rows separated by space, with a fill under the pointer.

Not permitted

A row faded to half strength to show it is unavailable.
Its words become too faint to read, and the row looks broken.
A line between each row of a short list.
The lines compete with the text and say nothing the space does not.

NextDisclosure

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

JSON

{
  "title": "List",
  "path": "/components/list",
  "url": "https://design.werklist.com/components/list",
  "text": "https://design.werklist.com/agent/components/list",
  "summary": "Stacks items of one kind in rows that a reader scans, opens or chooses from.",
  "version": "2.1.2",
  "kind": "component",
  "name": "List",
  "purpose": "Stacks items of one kind in rows that a reader scans, opens or chooses from.",
  "use": [
    "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."
  ],
  "avoid": [
    "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."
  ],
  "anatomy": [
    {
      "part": "Grouped card",
      "measure": "corner radius 24 px, padding 6 px, rows 2 px apart",
      "token": "--surface-1, --radius-3xl"
    },
    {
      "part": "Row in a grouped card",
      "measure": "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",
      "token": "--space-3, --type-product-subtitle"
    },
    {
      "part": "Row in a plain list",
      "measure": "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",
      "token": "--radius-lg, --space-2, --type-product-body"
    },
    {
      "part": "Row, two lines",
      "measure": "58 px in a card (10 px above and below, 20 px and 18 px lines), 50 px on a panel"
    },
    {
      "part": "Leading element",
      "measure": "icon 20 px, avatar 32 px or checkbox 16 px; --text-muted, --text on the current row"
    },
    {
      "part": "Second line",
      "measure": "Dense, 13 px on 18 px",
      "token": "--type-product-dense, --text-muted"
    },
    {
      "part": "Trailing element",
      "measure": "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",
      "token": "--text-muted"
    },
    {
      "part": "Group heading",
      "measure": "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",
      "token": "--type-product-dense, --text-label"
    }
  ],
  "sizes": [
    {
      "name": "grouped",
      "height": "46.5 px, 58 px with two lines",
      "padding": "12 px",
      "type": "Subtitle, 15 px, medium"
    },
    {
      "name": "plain",
      "height": "36 px under a mouse, 44 px on coarse pointers",
      "padding": "8 px",
      "type": "Body, 14 px on 20 px, medium"
    }
  ],
  "states": [
    {
      "name": "hover",
      "change": "faint fill; fine pointer only",
      "tokens": [
        "--glass-fill-hover"
      ]
    },
    {
      "name": "pressed",
      "change": "the same faint fill; a link row in a grouped card scales to 0.985",
      "tokens": [
        "--glass-fill-hover"
      ]
    },
    {
      "name": "current",
      "change": "tinted fill in --text, aria-current page; the other rows of the list turn --text-muted",
      "tokens": [
        "--nav-fill-active",
        "--text-muted"
      ]
    },
    {
      "name": "chosen",
      "change": "16 px tick at the end, aria-selected true; multiple choice uses a leading Checkbox",
      "tokens": [
        "--brand-blue"
      ]
    },
    {
      "name": "focus visible",
      "change": "2 px ring inside the row, offset minus 2 px",
      "tokens": [
        "--focus-ring"
      ]
    },
    {
      "name": "soon",
      "change": "the word Soon as the trailing value; not a link, aria-disabled true, not faded",
      "tokens": [
        "--text-muted"
      ]
    }
  ],
  "keys": [
    {
      "key": "Tab",
      "action": "Moves between links in a list of links; enters a list you choose from"
    },
    {
      "key": "Up and Down",
      "action": "Move between rows of a listbox"
    },
    {
      "key": "Home and End",
      "action": "First and last row"
    },
    {
      "key": "Space",
      "action": "Chooses or clears the focused row"
    },
    {
      "key": "Enter",
      "action": "Opens the focused row"
    },
    {
      "key": "Right",
      "action": "Moves into the row's own buttons"
    },
    {
      "key": "Left or Escape",
      "action": "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"
  ],
  "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."
  ]
}

Raw file: https://design.werklist.com/agent/components/list