# Card

A content container. Card is the clearest demonstration of the context system: the same component is a bordered, flat panel in product and a borderless, softly raised content block in marketing.

## Use it when
- Grouping related content that could stand alone: a plan, a setting group, a dashboard panel, a feature block.

## Don't use it when
- Everything on the page is a card. Nesting cards inside cards means neither is doing any work. Use `Stack` and a `Divider`.
- It is a list of similar rows. Use one container with row borders.

## Example
```jsx
<Card
  eyebrow="Best value"
  title="Team"
  description="Everything in Starter, plus shared workspaces."
  footer={<Button fullWidth>Choose Team</Button>}
/>
```

## Product vs marketing
Set by the context, not by a prop.

| | Product | Marketing |
|---|---|---|
| Padding | 16px | 32px |
| Border | 1px | none |
| Elevation | 0, raising to 1 | 0, raising to 2 |
| Radius | container (8px) | overlay (12px) |

If a card needs different treatment inside one context, that is a Tier 3 override on a wrapper, not a new prop.

## Tokens
`--dt-card-*`. Override these to restyle every card; override `--dt-surface-raised` to move all raised surfaces together.

## As a link
Pass `href` and the whole card goes there. The title becomes the one link a screen reader announces and a keyboard reaches; a copy of it, hidden from assistive technology, stretches over the card so a click anywhere lands. Put a real button in `footer`: it sits above the stretched link and keeps its own click.

```jsx
<Card href="/trips/ridge" title="Ridge loop" description="Four days, three huts." footer={<Button size="sm" variant="secondary">Save</Button>} />
```

## Over other content
`surface="glass"` makes the card the overlay surface, translucent, with `--dt-backdrop-glass` blurring whatever is behind it: a feed scrolling under it, a map, a soft gradient. It follows the colour mode. `surface="glass-inverse"` is dark in both modes, for a card over a photograph, and puts the `dark` class on the card so its title, text and any buttons inside read light on dark. Check the text against the real image behind it, as `guidelines/accessibility.md` describes.

```jsx
<Card surface="glass-inverse" title="Recovery" description="Your body is ready for a harder session." />
```

## With a picture behind it
`background` fills the card with an image and `backgroundVideo` with a muted, looping video, which doesn't autoplay for someone who prefers reduced motion (they see `background` as its still). The card is then dark in both colour modes: it scopes `.dark`, holds at least `--dt-card-media-min-height`, and sets its content at the bottom over `scrim`.

- `scrim="gradient"` (the default) darkens from the bottom, where the text sits. `solid` darkens the whole card. `none` is only for a picture already dark where the text lands.
- `onMedia` sets the text: `light` is the scrim's near-white, `white` is pure white for large type that would read as grey, and `primary` sets the title in a light brand step. Secondary text stays a quieter light either way.

```jsx
<Card background="/img/ridge.jpg" eyebrow="Guide" title="Ridge loop" description="Four days, three huts." onMedia="white" />
<Card backgroundVideo="/video/surf.mp4" background="/img/surf.jpg" scrim="solid" title="Morning session" onMedia="primary" />
```

The picture is decorative: say what matters about it in the title or description. Measure the text against the real picture, as `guidelines/accessibility.md` describes; a scrim is a floor, not a guarantee.

Tokens: `--dt-card-media-fg`, `--dt-card-media-fg-secondary`, `--dt-card-media-fg-strong`, `--dt-card-media-fg-brand`, `--dt-card-media-border` and `--dt-card-media-min-height`, aliasing `--dt-text-on-scrim*` and `--dt-size-media-min`.

## Accessibility
`interactive` is visual only. A clickable card needs a real control inside it, `href`, or `as="button"` with an accessible name. A div with onClick is not keyboard operable.

## Content
Eyebrow is two or three words. Title is a noun phrase. Description is one sentence.