# List

A list presents related items in an order that matters. Prefer native
`ul`/`ol` semantics for static content and introduce richer roles only when
the interaction model requires selection or composite keyboard behavior.

## Variants

- **Content list:** links or controls in ordinary document tab order.
- **Selection list:** one or more items can be selected and state is explicit.
- **Feed:** newly loaded entries preserve reading position and announce updates.
- **List/detail:** selection updates an adjacent detail region without obscuring
  which item is active.
- **Virtualized list:** rendering is bounded while position and count remain
  understandable.

## Item anatomy

Keep the primary label visually dominant. Put metadata, status, and trailing
actions in consistent columns. The entire row may be one link or button, but do
not place unrelated interactive controls inside that control. Use a dedicated
action menu when several secondary actions exist.

## Behavior

Define sorting, filtering, pagination or incremental loading, selection, empty
state, loading, error, and retry. Preserve selection when data refreshes if the
item identity remains valid. After deletion, focus moves to the next logical
item or the list heading.

## Accessibility

- Use ordered semantics only when order conveys meaning.
- Expose selection separately from focus.
- Label icon-only row actions with the item name.
- Do not force arrow-key navigation on an ordinary list of links.
- For virtualization, test screen-reader position announcements and avoid
  recycling focused nodes.

## Verification

Test long labels, mixed metadata, keyboard-only use, screen-reader navigation,
200% zoom, empty and one-item data, slow loading, stale refresh, and deletion of
the first, middle, and final item.