List view

Problem Context

• Items are objects such as tickets, messages, files, tasks, orders, people, alerts, search results, or resources.
• Users need to scan names and short summaries more than compare every item by the same set of columns.
• Rows may include status, metadata, unread state, thumbnail or icon, selection checkbox, trailing action, row menu, swipe action, or open-detail behavior.
• The list may be grouped, sorted, filtered, paginated, virtualized, synced with a details panel, or used as a source for bulk actions.

Selection Rules

• Choose list view when each row is a compact object summary and users scan primarily by name, title, snippet, status, or recency.
• Use table when aligned columns and header-to-cell comparison are central to the task.
• Use data grid when users edit cells, navigate cells with arrow keys, select ranges, copy and paste, or operate on keyboard-managed row widgets.
• Use details panel when the selected row needs durable adjacent detail beyond the row summary.
• Use card list, card grid, or collection when images, previews, varied item sizes, or visual discovery are more important than dense row scanning.
• Use feed or timeline when item order is event-centered and users consume a stream rather than manage a collection.
• Use listbox or select when the list is a form control for choosing values rather than a browsable object surface.
• Avoid list view when every row needs many comparable attributes that would become pseudo-columns.
• Avoid list view when row actions are more important than identifying the item.
• Avoid list view when rows cannot keep labels, metadata, status, and actions readable at the target viewport width.

Required States

• Default list state with label or heading, row count or context, visible row summaries, and primary row identity.
• Focused row or focused row action state with visible focus and accessible row identity.
• Selected row, multi-selected row, bulk-selection count, and selected-away state when selection is supported.
• Active row state when a row controls a details panel, preview panel, route, or selected object context.
• Unread, new, updated, pinned, priority, archived, disabled, unavailable, or locked row states when applicable.
• Row action menu, primary row action, secondary trailing action, swipe action, and destructive action states.
• Grouped, sorted, filtered, searched, paginated, infinite-loaded, virtualized, and loading-more states.
• Empty list, no-results, permission-limited, loading, partial-load, and failed-load states.
• Narrow-screen state with stacked metadata, reachable actions, and preserved row identity.
• Detail-open or preview-open state when list selection drives adjacent or routed detail.

Interaction Contract

• Each row has one primary object identity that remains visible across selection, hover, focus, filtering, and responsive states.
• The row's primary action, checkbox, menu, and trailing action have distinct hit targets and accessible names that include the item identity.
• A row click opens, selects, or previews according to one stable rule; secondary actions do not conflict with that rule.
• Selection state is not confused with focus, hover, unread, active-detail, or checked status.
• Sorting and filtering update row order or membership while preserving selected rows, active detail context, and scroll position when possible.
• Grouping labels describe meaningful sets and do not replace row-level identity.
• Virtualized or infinite lists preserve row labels, row positions, loading boundaries, and focus restoration.
• Bulk actions clearly state which visible or hidden selected rows are affected.

Implementation Checklist

• Define the row object, primary label, supporting text, metadata fields, status indicators, leading media, and available row actions.
• Choose list semantics for ordinary object rows, listbox semantics only for option selection, or grid semantics only when row interaction needs grid navigation.
• Give the list a heading or accessible label and expose row count, active filters, and selection count near the list.
• Keep row layout stable: primary text, secondary text, metadata, status, and actions should not jump when rows are selected, updated, or hovered.
• Label icon-only row actions with the object identity, such as Archive ticket TCK-1042.
• Define whether row activation opens detail, toggles selection, previews, expands, or navigates, and keep it consistent.
• Support empty, no-results, loading, error, selected, active, unread, pinned, disabled, sorted, filtered, paginated, and virtualized states deliberately.
• Test keyboard navigation, screen reader row identity, row action labels, selection count, virtualized focus restoration, long labels, localization, zoom, and mobile hit targets.

Common Generated-UI Mistakes

• Using list view as a table without column headers or column-state feedback.
• Putting too many independent controls in every row until the list becomes a keyboard trap.
• Making the entire row, title link, checkbox, and trailing icon all trigger different undocumented actions.
• Using color alone to show unread, selected, active, pinned, or failed rows.
• Hiding status, owner, due date, or selection state on mobile so rows become indistinguishable.
• Letting filters remove selected rows without explaining whether bulk actions still affect hidden selections.
• Virtualizing rows without stable row labels, positions, loading boundaries, or focus recovery.
• Repeating the same row summary in a details panel without adding useful detail.

Critique Questions

• What does one row represent and what text uniquely identifies it?
• Is the user scanning object summaries, comparing columns, editing cells, or inspecting one selected object?
• What is the row's primary action, and which controls are separate secondary actions?
• Can users distinguish focus, selection, active detail, unread, pinned, disabled, and hover states?
• What happens to selected rows and active detail after sort, filter, pagination, refresh, or virtualization?
• Would table, data grid, details panel, card layout, feed, timeline, listbox, or tree grid better fit the task?