Patterns

A list people work with

Header, filters, a table with its tools and a pager: the screen most plugins have.

The most repeated screen of a plugin is a list the user works on: courses, participants, rules, logs. It is built with the same pieces every time, in the same order, so people know where each one is.

When to use it

The user has many things of one kind and has to find, compare or act on them.
Each thing has several attributes that are worth comparing (a table), not just a name and a line (then use a list group).
Do not use it for fewer than about five items, or for things that are better looked at one by one (cards or a detail page).

Anatomy

Page header (dd-page-header): where you are, the title with its context and the main action of the page.
Filter chips (dd-chips): the three to six filters used all the time, with their counts.
Card with the table: the toolbar (search, secondary actions), the table and, under it, the pager.
Actions of a row, always visible, at the end of the row.

A list for working

		Status
Algebra I	128	Open
Physics II	94	Draft
World history	156	Closed

Layout and spacing

Between	Distance
Header and chips	1 rem
Chips and card	1 rem
Toolbar and table	0, a hairline separates them
Table and pager	0, inside the same card
Cells	0.75 rem above and below, 1 rem at the sides
Row actions	2 px between icon buttons

The card is the whole width of the column. The first column grows; numbers and actions keep their natural width.

Behaviour

Typing in the search narrows the list after a short pause (about 300 ms), never on every key press, and the count in the header changes with it.
A chip applies at once and goes to the first page. Several chips of different kinds combine; chips of the same kind replace each other.
Clicking a sortable header sorts by that column; the same click again reverses it. One column is sorted at a time and the arrow shows which.
A row is opened by its name; the icon buttons at its end are the quick actions (edit, hide). A destructive one asks for confirmation.
Changing the rows per page goes back to the first page.
The state of the list (search, chips, sort, page) is kept in the address, so a link or a reload comes back to the same list.

States

State	What the user sees
Loading	The table keeps its height with skeleton rows; the pager is hidden
Empty, first time	The empty state of the first time, inside the card, with the action that creates the first item
Empty, after a search or a filter	The empty state of a search, with a button that clears the filters
Error	An alert above the table that says what failed and a “Try again” button
No permission	An empty state that says who can see the list

Narrow screens

The table scrolls sideways inside its card; the first column stays visible. The toolbar wraps: the search takes the whole width and the actions go below it. The pager keeps the arrows and drops “Rows per page”.

Accessibility

The table has a caption (visible or hidden) that names it, and each header is a th scope="col"; the first cell of a row is a th scope="row".
The sorted column has aria-sort; the sort buttons are buttons.
The count and the results announce themselves in a polite live region (“7 results”).
Icon buttons have a title and an aria-label that names the row (“Edit Algebra I”).

Before shipping

One filled button in the whole screen.
Every state above exists.
The state of the list is in the address.
Sorting, filtering and paging work with the keyboard only.
A destructive row action asks first.