Card list

Problem Context

• Items are objects such as opportunities, articles, courses, products, files, people, reports, cases, media assets, or search results.
• Each item benefits from multiple information types: image or icon, title, description, metadata, status, owner, date, tags, and actions.
• Users are browsing or triaging rather than doing strict column comparison or spreadsheet-like editing.
• The surface may be filtered, sorted, paginated, infinitely loaded, selectable, expandable, or paired with a preview or detail route.

Selection Rules

• Choose card list when each item needs more context, imagery, or mixed metadata than a dense row can comfortably show.
• Choose card list when a single-column order is important and users should read one rich summary at a time.
• Use list view when compact scanning, aligned row placement, and high item density matter more than rich card summaries.
• Use collection when the item set itself has title, owner, membership, sharing, ordering, or management behavior.
• Use browse by category when cards are topic or category destinations rather than object summaries.
• Use table or data grid when users need aligned comparison, numeric analysis, column sorting, range selection, or cell editing.
• Use details panel or preview panel when the card should remain compact and detailed inspection belongs beside or beyond the list.
• Avoid card list when card chrome does not add decision-making value beyond a simple row.
• Avoid card list when inconsistent card heights and anatomy make scanning or comparison harder than rows.
• Avoid card list when the main task is seeing many thumbnails at once in multiple columns.

Required States

• Default card list with heading or label, result count, and visible card summaries.
• Card default, hover, focus, active, selected, disabled, loading, unavailable, saved, new, updated, and error states.
• Primary card activation state and separate secondary action, overflow menu, save, share, select, and destructive action states.
• Expanded card and collapsed card states when summaries reveal more detail inline.
• Filtered, sorted, searched, paginated, loading-more, no-results, empty, and failed-load states.
• Hidden selected, selected-away, bulk action, and saved-count states when selection or saving is supported.
• Responsive narrow-screen state with stable title, summary, metadata, status, and actions.
• Long title, missing image, missing metadata, mixed media type, permission-limited, and stale item states.

Interaction Contract

• Each card represents one object or concept and exposes one primary identity that stays visible across all states.
• The card's primary activation, secondary buttons, menu, selection control, and destructive actions have distinct hit targets and accessible names.
• Card anatomy remains consistent enough that users can predict where title, status, metadata, and actions appear.
• Filtering and sorting update card order or membership without losing selected, saved, expanded, or focused card state unexpectedly.
• Expansion reveals additional summary detail without moving key controls out of reach or hiding the card's primary identity.
• Loading more cards preserves scroll position, focus, card labels, and result counts.
• Missing images or unavailable previews have meaningful fallbacks that do not collapse card dimensions.
• Bulk or saved actions state whether they affect visible cards, selected cards, hidden selected cards, or the whole result set.

Implementation Checklist

• Define the card object, primary title, preview media, summary, metadata fields, status labels, primary action, secondary actions, and optional selection model.
• Use semantic list markup for the card sequence and article, link, button, checkbox, or menu semantics inside each card according to behavior.
• Give the card list a heading or accessible label and expose result count, active filters, selected count, and saved count near the list.
• Keep card anatomy stable across missing media, long text, selected state, hover, focus, and responsive widths.
• Label icon-only card actions with the card title, such as Save Grant opportunity G-2048.
• Separate card click, title link, Save, More actions, selection checkbox, and destructive actions so their hit targets do not overlap.
• Design empty, no-results, loading, failed-load, saved, selected, expanded, unavailable, permission-limited, and missing-preview states.
• Test keyboard order, focus visibility, screen reader card identity, action labels, long text, localization, zoom, mobile wrapping, and missing image fallbacks.

Common Generated-UI Mistakes

• Using cards as decorative wrappers for dense rows.
• Making the entire card clickable while nesting conflicting buttons or links inside it.
• Changing card anatomy item by item until scanning becomes unpredictable.
• Hiding key metadata behind expansion when users need it to choose among cards.
• Using card list for strict price, date, owner, or numeric comparison that needs aligned columns.
• Letting images define the card when missing or low-quality images are common.
• Showing many secondary actions on every card until the list becomes an action maze.
• Failing to preserve selected, saved, or expanded card state after sort, filter, or load more.

Critique Questions

• What extra decision support does the card provide that a compact row cannot?
• Is the user browsing rich summaries, comparing attributes, managing a named set, or navigating categories?
• What is the card's primary activation, and which actions are separate secondary controls?
• Can users predict where title, status, metadata, and actions appear on every card?
• What happens to saved, selected, expanded, and focused cards after sorting, filtering, or loading more?
• Would list view, table, data grid, collection, details panel, preview panel, or browse by category better fit the task?