# ren-card

Container primitive for grouped content with header, body, footer, status,
and interactive (clickable / selectable) variants.

Load this file after `ren-design.md` and before generating, editing, or
reviewing any `.ren-card` UI.

## Purpose

Owns the shape, padding, surface, and border of grouped content. Provides
slots (`-header`, `-body`, `-footer`) and a small set of variants
(`-elevated`, `-outline`, `-sunken`, `-ghost`, `-simple`,
`-interactive`, `-selectable`) plus a status hook (`[data-status]`).
Card never owns inputs, dialogs, or navigation behavior — it is a passive
container.

## Use When

- A group of related content needs its own surface separated from the page.
- A list of repeating items would benefit from a consistent card grid
  (`ren-grid` + `ren-card`).
- A tile must be clickable or selectable as a whole (use
  `.ren-card-interactive` or `.ren-card-selectable`).
- A surface needs a header / body / footer layout already proven by RenDS.

## Do Not Use When

- The container is just a layout primitive — use `ren-stack`, `ren-cluster`,
  `ren-grid`, etc.
- The container is a modal — use `ren-dialog`.
- The container is a popover / tooltip / menu — use those composites.
- You need an alert / banner / call-out — use `ren-banner`.
- You need a form section — use `ren-form` + `ren-field` directly.

## aiHints

```yaml
selectionCriteria:
  useWhen:
    - "You want a visually grouped surface (border / shadow / radius) with predictable spacing."
    - "You need a card grid (stat tiles, product cards, list items)."
    - "You need a whole-card click target (.ren-card-interactive) or selection (.ren-card-selectable)."
    - "You need a status accent driven by [data-status]."
  avoidWhen:
    - "You only need vertical spacing — use ren-stack."
    - "You need overlay behavior — use ren-dialog / ren-popover / ren-sheet."
    - "You need a banner / alert message — use ren-banner."
    - "You need a navigation list with hover / active — use ren-sidebar items."

canonicalImports:
  css:
    - "rends/components/primitives/ren-card/ren-card.css"
  notes:
    - "Card is CSS-only. There is no <ren-card> custom element."
    - "If the page already imports rends/components/index.css, do not import the CSS again."

requiredMarkup:
  - "A single .ren-card root wrapping any number of .ren-card-header, .ren-card-body, .ren-card-footer."
  - ".ren-card-title is the heading; use a real <h*> element inside it for outline / a11y."
  - "Selectable cards must wire a state attribute AND a keyboard handler — the class only styles. Pick the attribute the card's role allows: aria-pressed on a <button>, aria-checked with role=\"radio\"/\"checkbox\", a real checked <input> inside a <label>, or [data-selected] for a decorative sample. aria-selected is legal only on option/tab/row/gridcell/treeitem — on a bare <div> or <label> it fails aria-allowed-attr."
  - "Interactive cards (whole-card click) should wrap content in a real <a> or <button>, not a div with onclick."
  - "Media uses .ren-card-cover as a direct child: either <img class=\"ren-card-cover\" alt=\"...\"> or a wrapper (<div> or <figure class=\"ren-card-cover\">) with one <img> inside. The slot is edge-to-edge in either position (first or last)."
  - ".ren-card-simple is only for sectionless content. Do not combine it with header, body, footer, footer-border, or cover — the root padding would stack on those slots."

forbiddenPatterns:
  - "Nesting another .ren-card inside .ren-card-body — flatten the structure."
  - "Replacing internal .ren-card-* selectors with custom classes for theming — use --ren-card-* tokens."
  - "Hardcoded shadow / radius values overriding card defaults; theme through tokens."

tokenPolicy:
  allowed:
    - "Component tokens: every --ren-card-* listed in Public Token API."
    - "Semantic tokens for content inside the card (--color-text, --color-text-muted, etc.)."
  forbidden:
    - "Primitive palette tokens (--blue-*, --gray-*, etc.) in consumer code."
    - "Hardcoded hex / rgb colors in consumer overrides."

accessibility:
  required:
    - "Card titles use real heading elements (<h2>, <h3>) — never style a <div> as a heading."
    - "Whole-card click targets must use <a> or <button> wrappers and respect tab order / focus rings."
    - "Selectable cards announce state through an attribute their role supports (aria-pressed on <button>, aria-checked with role=radio/checkbox, or a real <input>); [data-selected] is a styling hook only and announces nothing."
    - "Never put aria-selected on a role-less .ren-card — it is a prohibited attribute there, not a state."
    - "[data-status] is decorative; pair it with meaningful text or icons, not color alone."
```

## Required CSS / JS Imports

```html
<link rel="stylesheet" href="rends/components/primitives/ren-card/ren-card.css">
<!-- No JS — card is CSS-only. -->
```

## Canonical Markup

Static card with header + body:

```html
<article class="ren-card">
  <div class="ren-card-header">
    <h3 class="ren-card-title">Project status</h3>
    <p class="ren-card-description">Updated 2 minutes ago.</p>
  </div>
  <div class="ren-card-body">
    <p>All checks passing.</p>
  </div>
</article>
```

Interactive (whole-card click) with link wrapper:

```html
<a class="ren-card ren-card-interactive" href="/projects/atlas">
  <div class="ren-card-header">
    <h3 class="ren-card-title">Atlas</h3>
  </div>
  <div class="ren-card-body">42 open issues</div>
</a>
```

Selectable in a grid (toggle form — `aria-pressed` drives both the semantics
and the accent ring):

```html
<div class="ren-grid-3">
  <button class="ren-card ren-card-selectable" type="button" aria-pressed="false">
    <span class="ren-card-title">Hobby</span>
    <span class="ren-card-description">$0/mo</span>
  </button>
</div>
```

Exclusive choice (radio form — the real `<input>` carries the state, and
`:has(:checked)` paints the ring; no ARIA needed):

```html
<label class="ren-card ren-card-selectable">
  <input type="radio" name="plan" class="ren-sr-only" checked>
  <span class="ren-card-title">Pro</span>
  <span class="ren-card-description">$12/mo</span>
</label>
```

## Variants

| Class                   | Role                                      |
|-------------------------|-------------------------------------------|
| `.ren-card`             | Default surface.                          |
| `.ren-card-elevated`    | Adds shadow.                              |
| `.ren-card-outline`     | Border-only, transparent fill.            |
| `.ren-card-sunken`      | Inset surface (sunken background).        |
| `.ren-card-ghost`       | No surface; spacing only.                 |
| `.ren-card-simple`      | One root padding for sectionless content. |
| `.ren-card-interactive` | Hover / focus styles for clickable cards. |
| `.ren-card-selectable`  | Selectable surface; use role-appropriate state. |
| `.ren-card-cover`       | Edge-to-edge media slot (image or wrapper). |
| `.ren-card-group`       | Joined sibling cards with shared borders. |
| `.ren-card-footer-border` | Footer with top divider.                |

## Slot spacing

Direct children of `.ren-card` fall into two groups. Named slots own their
padding. Everything else is loose content and only the first and last loose
children receive `--ren-card-padding` on the outer edge.

| Slot | Markup | Block padding |
|---|---|---|
| Header | `.ren-card-header` | `--ren-card-padding` on top and inline edges; bottom is `0`. |
| Body | `.ren-card-body` | `--ren-card-padding` on every side. After a header, top tightens to `--space-3`. |
| Footer | `.ren-card-footer` | `--ren-card-padding` on bottom and inline edges; top is `0`. |
| Bordered footer | `.ren-card-footer-border` | `--space-3` block, `--ren-card-padding` inline, plus a top divider. After a header, top tightens to `--space-2`. The first/last-child fallback does not add `--ren-card-padding` on top of this. |
| Cover, image | `<img class="ren-card-cover" alt="...">` | `0` on every side, first or last. The image is `width: 100%`, `display: block`, `object-fit: cover`, and sits flush with the card's border box. |
| Cover, wrapper | `<div class="ren-card-cover">` or `<figure class="ren-card-cover">` with one `<img>` | The wrapper is flush (`margin: 0`, `padding: 0`) in either position. The inner image fills the wrapper the same way. |
| Loose content | Any other first/last child, such as a `<p>` | `--ren-card-padding` on the outer edge only (`padding-top` if first, `padding-bottom` if last). |
| Simple | `.ren-card.ren-card-simple` around sectionless content | `--ren-card-padding` once, on the card root. Children do not receive the loose-content fallback. |

Adjacent named slots (header, body, footer, footer-border) separate with
`--ren-card-gap` (default `0`). Cover is not part of that stack, so it does
not pick up section gap or section padding.

Give the image an `alt`. A decorative cover uses `alt=""`. Do not put
`.ren-card-cover` inside `.ren-card-simple` or `.ren-card-body` — those
parents already inset their content, and the cover would no longer be
edge-to-edge.

## States

| Selector / attr        | Meaning                                     |
|------------------------|---------------------------------------------|
| `:hover` / `:active`   | Pointer interaction (interactive cards).    |
| `:focus-visible`       | Keyboard focus ring (interactive cards).    |
| `[aria-selected="true"]` | Selection state — only on a card whose role supports it (option / tab / row / gridcell / treeitem). |
| `[aria-pressed="true"]` | Selection state for the `<button>` form.    |
| `[aria-checked="true"]` | Selection state for `role="radio"` / `role="checkbox"`. |
| `:has(:checked)`       | Selection driven by a real `<input>` inside a `<label>` card. |
| `[data-selected]`      | Decorative selection styling; announces nothing. |
| `[data-status="success" / "warning" / "danger" / "info"]` | Status accent. |

## Public Token API

- `--ren-card-bg`
- `--ren-card-border-color`
- `--ren-card-border-width`
- `--ren-card-radius`
- `--ren-card-padding`
- `--ren-card-gap`
- `--ren-card-header-gap`
- `--ren-card-shadow`

## Accessibility Contract

- Card titles are real `<h*>` elements; never style a `<div>` as a heading.
- Whole-card clickability wraps the entire card in a real `<a>` or `<button>`.
- Selectable cards must expose the state attribute their role allows —
  `aria-pressed` on a `<button>`, `aria-checked` with `role="radio"` /
  `role="checkbox"`, or a real `<input>` — plus a visible focus ring via
  `:focus-visible`. `aria-selected` is reserved for cards that carry
  `option` / `tab` / `row` / `gridcell` / `treeitem`; anywhere else it is a
  prohibited attribute (axe: `aria-allowed-attr`).
- `[data-status]` is decorative; status meaning must be carried by text or
  icons too.

## Anti-Patterns

- ❌ `<div class="ren-card" onclick="...">` — wrap with a real link / button.
- ❌ Nesting `.ren-card` inside `.ren-card-body`.
- ❌ `<div class="ren-card ren-card-selectable" aria-selected="true">` — a
  role-less card cannot carry `aria-selected`. Use `aria-pressed` on a
  `<button>`, `aria-checked` with an explicit role, a real `<input>`, or
  `[data-selected]` when the card is only a visual sample.
- ❌ Inline hex colors on `.ren-card { background: #FFFFFF; }` — override
  `--ren-card-bg` on the parent scope.
- ❌ Replacing built-in selectors (`.ren-card-title`) with custom classes
  for theming — theme through component tokens.
- ❌ Putting padding or margin on `.ren-card-cover` to "inset" a photo —
  the slot is edge-to-edge; inset media belongs in `.ren-card-body`.
- ❌ Combining `.ren-card-simple` with header, body, footer, or cover —
  simple padding is the root padding for sectionless content only.

## Related Files

- `components/primitives/ren-card/ren-card.css`
- `docs/components/ren-card.html`
- `ren-design.md`
- `tokens/tokens.md`
- `base/layouts.md`

## Test Expectations

- Run component or docs a11y coverage when markup, ARIA, or states change.
- Run `npm run lint` after token / selector changes.
- Manually verify light/dark themes when surface, border, or shadow values
  change.

## Density and color mode

Use `data-density="compact|comfortable|spacious"` on the root or a subtree. Bare stacks, card padding, and form field rhythm respond to the scope; fixed stack size modifiers and explicit component token overrides retain their values. Default card padding remains 16px; compact is 12px and spacious is 32px. Use `data-mode="light|dark|auto"` independently of a named `data-theme`; legacy `data-theme="light|dark"` remains supported.
