Card grid

Problem Context

• Items are peer objects such as products, courses, files, templates, assets, locations, people, articles, media, reports, or examples.
• Users choose from visual or semi-visual summaries instead of reading every item in full.
• The result set may be filtered, sorted, searched, selected, saved, paginated, infinitely loaded, or displayed at multiple densities.
• Cards may contain thumbnail, title, short label, rating, price, status, owner, file type, duration, tags, and one or two object actions.

Selection Rules

• Choose card grid when users need to see multiple objects at once and visual preview or compact card identity helps them choose.
• Choose card grid when items are peers with comparable card anatomy and no collection-level membership behavior.
• Choose card grid when the layout can reflow across breakpoints without hiding title, preview, state, selection, or primary actions.
• Use card list when each object requires a longer summary, more metadata, or a stronger single-column reading sequence.
• Use collection when the item set has a title, owner, saved membership, sharing, ordering, sections, or add and remove behavior.
• Use table or data grid when aligned attribute comparison, numeric ranking, row operations, cell editing, or dense scanning is the main task.
• Use browse by category when each card is a topic or taxonomy destination rather than an object card.
• Use carousel only when a small curated subset is sequentially featured and not every card needs simultaneous visibility.
• Avoid card grid when images are decorative, missing, or inconsistent enough to dominate the layout without improving choice.
• Avoid card grid when users need to compare exact values that would be clearer in columns.

Required States

• Default grid with heading or label, result count, active view controls, and at least one full row of peer cards.
• Card default, hover, focus, active, selected, saved, unavailable, loading, failed-thumbnail, missing-thumbnail, disabled, and opened states.
• Grid filtered, sorted, searched, compact density, comfortable density, loading-more, paginated, empty, no-results, and failed-load states.
• Responsive one-column, two-column, three-column, and wide multi-column states with stable gutters and preserved card order.
• Selected-away, hidden selected, bulk action, saved count, item removed, item added, and restored item states when selection or saving is supported.
• Long title, missing image, mixed media type, permission-limited, stale item, duplicate title, and unavailable action states.

Interaction Contract

• Each card represents one object and keeps title, preview, key metadata, state, and actions in the same relative positions across cards.
• Visual order, DOM order, keyboard order, and screen-reader order remain consistent after responsive reflow.
• Card activation, selection, save, overflow, and destructive actions have separate hit targets and accessible names that include the object title.
• Grid-level filters, sort controls, density switches, pagination, and load-more controls update counts and preserve object-keyed selected, saved, and focused state.
• Missing images use a reserved fallback area so card height, row alignment, focus position, and action placement do not jump.
• Column-count changes do not convert card grid behavior into a hidden carousel, a masonry layout with confusing order, or a dense table without headers.
• Bulk actions state whether they affect visible cards, selected cards, hidden selected cards, or all matching cards.
• When users need exact comparison, the surface offers a sort, filter, details view, compare mode, table view, or other clear path instead of forcing visual hunting.

Implementation Checklist

• Define card anatomy: thumbnail or icon, title, secondary label, compact metadata, status, price or rating if relevant, primary action, selection control, save control, and overflow action.
• Set grid minimum card width, maximum columns, gutters, row gaps, preview aspect ratio, title line limits, and responsive breakpoints before binding live content.
• Render the card set as a list or grid with accessible labelling, object-keyed IDs, visible result count, selected count, saved count, and active filters.
• Keep interactive descendants separate rather than placing multiple buttons and links inside one wrapping card button.
• Provide stable fallbacks for missing previews, long titles, unavailable items, mixed media, duplicate names, and permission-limited cards.
• Preserve selected, saved, expanded, focused, and recently acted-on cards across sort, filter, density change, breakpoint reflow, pagination, and loading more.
• Offer keyboard operation for selection, save, overflow, bulk actions, load more, and any reorder or compare controls.
• Test screen reader order, zoom, localization, high contrast, long text, reduced width, pointer target spacing, async loading, and virtualized grids.

Common Generated-UI Mistakes

• Using card grid as decorative chrome for rows that need dense scanning or aligned comparison.
• Allowing every card to choose its own image ratio, title placement, metadata order, and action area.
• Treating a grid of result cards as a collection without collection identity, owner, count, or membership rules.
• Hiding important card actions behind hover-only affordances that vanish on touch and keyboard.
• Tracking selected cards by index, so filtering, sorting, or responsive reflow changes which object is selected.
• Using masonry layout for task-critical keyboard navigation without a clear reading order.
• Letting missing thumbnails collapse cards and break row alignment.
• Putting too many visible actions in every card until the grid becomes a tab-stop maze.

Critique Questions

• What does the grid reveal by showing several cards at once that a card list would slow down?
• Are users visually browsing peer objects, managing a named collection, navigating categories, or comparing columns?
• Which fields must appear in the same place on every card for scanning to work?
• How does the grid preserve selected, saved, focused, and acted-on cards after filtering, sorting, loading, and breakpoint changes?
• What fallback keeps missing previews from changing card height or keyboard order?
• When exact comparison becomes important, what route to table, sort, filter, compare, or details view is provided?