# Card Grid

## Essence

Generic repeated-card layout component.

`Card Grid` owns only the grid layout for card-like children. It does not know whether the children are homepage cards, project cards, artifact cards, notes, or placeholders.

## Hook

Use when a section needs to display multiple cards in a consistent responsive grid.

## Internal Rules

- Renders arbitrary slotted children.
- Uses token-based gaps.
- Width fills the parent.
- Height wraps content.
- Supports `density = comfortable` and `density = compact` for current homepage section needs.
- On tablet breakpoint, renders two cards per row.
- Treats density as layout intent, not a permanent promise of exact column count on every breakpoint.
- On mobile breakpoint, both density values render one card per row.
- Does not duplicate or inspect child card internals.
- Does not own section titles, descriptions, or page order.

## Use When

- A homepage section needs repeated cards.
- A content section needs a reusable card layout.
- The parent component owns the cards, but needs consistent spacing and layout density.

## Do Not Use When

- The component needs to render one specific card; use that card component directly.
- The layout is not card-like repeated content.
- The parent needs masonry, carousel, table, or list behavior.
- The grid would need to know child content schema.

## Props

| Prop | Values | Purpose |
| --- | --- | --- |
| `density` | `comfortable`, `compact` | Layout density intent for the grid. |
| slot | Astro slot | Card-like children supplied by the parent component. |

## Accessibility Notes

- `Card Grid` does not add semantics by itself.
- Child cards keep their own semantic elements and link behavior.
- Parent sections should provide headings and context around the grid.

## Related Components And Patterns

- `Article Card`: one possible child card.
- `Article Hero`: one parent that uses Card Grid for latest article cards.
- `Homepage Hero`: not a card-grid child.
- Parent containers own any background behind the grid.
- `Stub Object`: useful only in Design System previews for abstract card slots.

## Code Paths

- `packages/design-system/src/components/CardGrid.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`
- `apps/portfolio-site/src/pages/design-system/essences/[slug].md.ts`