# Responsive Card Grid

## Objective

Make card grids reflow at every width without crushed columns or sideways scroll.

A shared grid behaviour for card collections that chooses its column count from the available width and the card's own minimum readable width.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Find every collection of cards in the app — dashboards, galleries, pricing tiers, project lists — and drive them all from one grid behaviour rather than a per-screen set of breakpoints.
2. Derive the column count from a minimum readable card width and the space actually available, so the grid adapts inside a narrowed sidebar or a modal, not only at the window's breakpoints.
3. Decide deliberately whether cards in a row stretch to a common height or keep their natural heights, and apply that decision consistently. Mixed behaviour within one grid reads as a bug.
4. Constrain long unbroken strings — URLs, file names, identifiers, tokens without spaces — inside the card so they wrap or truncate rather than widening the column and forcing the page to scroll horizontally.
5. Do not reorder cards visually to fill gaps. Absolute positioning or column-first flow separates the reading order from the DOM order, which breaks keyboard tabbing and screen reader sequence; keep source order and accept the ragged last row.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A card's minimum width must come from what it contains — a title, a stat, a set of controls — not from an arbitrary pixel value that leaves the contents crushed at one size and stranded at another.
- Visual order and DOM order must stay identical, so that tabbing through the grid and reading it aloud follow the same path the eye takes.
- Cards with different content lengths will not naturally match in height. Either equalise them within a row or let them ride, but say which, and make sure the taller card does not leave a hole beneath its neighbour.
- A single long unbroken token inside one card must not set the width of the whole column and push the layout past the viewport.
- The final row with one or two cards must not stretch them across the full width; leave the gap.
- An empty collection needs its own state rather than an empty grid container that collapses to nothing.
- Images and media inside cards are governed by Media Aspect Ratio System — the grid owns column count and gutters, the media system owns the shape of what sits inside a card.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Card grids reflow based on their container's width, not only the viewport's.
- [ ] No layout width causes horizontal scrolling on the page body.
- [ ] Tab order and reading order match the visual order at every column count.
- [ ] Long unbroken strings wrap or truncate inside the card and never widen the column.
- [ ] Height behaviour within a row is uniform across every grid in the app.
- [ ] A partially filled last row leaves cards at their normal width.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.