# Card

> Componentes / Conteúdo · Estado: **Em andamento** — Implementado e utilizável, mas ainda sem a validação completa de acessibilidade.

A superfície que agrupa um conteúdo, com partes que cuidam do próprio espaço — `CardMedia` (imagem de ponta a ponta), `CardHeader`, `CardTitle`, `CardDescription`, `CardContent` e `CardFooter` — em quatro tratamentos, um deles para o cartão clicável inteiro.

- Função: Conteúdo
- Também chamado de: cartão, card, bloco, caixa
- Mora em: `app/components/atoms/Card.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/Card](https://phorte-design-system.vercel.app/styleguide/peca/Card)
- Ficha no Storybook: [components-complex-card](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-card--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/Card/0](https://phorte-design-system.vercel.app/previa/Card/0)
- Todas as peças: [https://phorte-design-system.vercel.app/llms.txt](https://phorte-design-system.vercel.app/llms.txt)

## Como usar no código

```tsx
import { Card } from '@/app/components/atoms/Card';

<Card>…</Card>
```

## Uso

### Variantes na ficha

1. [Cartão de curso](https://phorte-design-system.vercel.app/previa/Card/0)
2. [Com mídia](https://phorte-design-system.vercel.app/previa/Card/1)
3. [Variantes](https://phorte-design-system.vercel.app/previa/Card/2)
4. [Clicável](https://phorte-design-system.vercel.app/previa/Card/3)

Para agrupar informação sobre uma coisa só — um curso, um post, uma estatística — que se repete numa grade.

### Quando não usar

Para curso, post ou evento, use a peça pronta (CourseCard, BlogCard, EventCard). Para um número com rótulo, o StatCard. Para separar seções da página, espaço e título (SectionTitle), não caixas.

### Faça

- Monte com as partes: cada uma já tem o seu preenchimento.
- Use `CardMedia` para imagem de ponta a ponta, com a proporção (`16/9`, `4/3`, `1/1` ou `livre`).
- Acerte o nível do título com `as` no `CardTitle` (`h3` por padrão).
- Para cartão clicável inteiro, `variant="interactive"` com o `CardLink` no título (E68): um link só, estendido sobre o cartão.
- Use `as="article"` quando o cartão é um item que vale sozinho numa grade (curso, notícia, evento); `li` dentro de lista.

### Evite

- Somar preenchimento no cartão e nas partes ao mesmo tempo: o espaço dobra.
- O cartão inteiro como link com outros controles dentro — são interativos aninhados.
- `interactive` sem link dentro: o hover promete um clique que não existe.

### Nota de uso

O `Card` é só a superfície; **cada parte cuida do próprio espaço** (`CardHeader`, `CardContent`, `CardFooter` com `p-6`). Não some padding no cartão e no conteúdo ao mesmo tempo — era assim que o espaço dobrava. Para imagem de ponta a ponta, use `CardMedia`. Para cartão clicável inteiro, `variant="interactive"` com o **`CardLink`** no título (E68): um link só, estendido sobre o cartão, com o título como nome — nunca o cartão inteiro como link com outros controles dentro. O anel acende só no foco por teclado. `as="article"` para item de grade. O `CardTitle` aceita `as` para acertar o nível do cabeçalho.

### Anatomia

1. **Cartão** — `--card`, cantos `rounded-xl`, borda e sombra conforme a variante.
2. **Mídia** — `CardMedia`: imagem de ponta a ponta na proporção escolhida, fundo `--muted`.
3. **Cabeçalho** — `CardHeader`: título (`CardTitle`) e descrição (`CardDescription`), `p-6 pb-0`.
4. **Conteúdo** — `CardContent`, `p-6`.
5. **Rodapé** — `CardFooter`: preso embaixo (`mt-auto`), com borda em cima.
6. **Link** — `CardLink` (E68): o link do título, com `after:absolute after:inset-0` cobrindo o cartão; `novaAba` avisa a outra aba.

### Estados

| Estado | O que muda |
| --- | --- |
| Padrão | `default`: borda `--border` e sombra leve. |
| Elevado | `elevated`: sombra grande. |
| Contorno | `outline`: borda `--border-interactive`, sem sombra. |
| Interativo | `interactive`: `relative`; no hover, borda de controle e sombra maior; com o foco **por teclado** no link de dentro, o anel de foco em volta do cartão (`has-focus-visible`, E68 — o `focus-within` acendia também no clique). |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Grade de cartões com alturas diferentes | O `CardFooter` fica colado embaixo (`mt-auto`), alinhando os rodapés. |
| Foco por teclado no link de dentro (`interactive`) | O cartão inteiro ganha o anel de foco; no clique de mouse, não. |
| Clique em qualquer lugar do cartão clicável | Cai no `CardLink` — conferido no teste da ficha (um clique na descrição chega ao link). |

### Relacionados

- [CourseCard](https://phorte-design-system.vercel.app/styleguide/md/CourseCard.md) — O cartão de curso, pronto.
- [StatCard](https://phorte-design-system.vercel.app/styleguide/md/StatCard.md) — Um número com rótulo.
- [BlogCard](https://phorte-design-system.vercel.app/styleguide/md/BlogCard.md) — O cartão de post, pronto.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `variant` | `'default' \| 'elevated' \| 'outline' \| 'interactive'` | `'default'` | não | Variante do `cva`. |
| `as` | `'div' \| 'article' \| 'section' \| 'li'` | `'div'` | não | O elemento da raiz (E68). `article` quando o cartão é um item que vale sozinho — um curso, uma notícia, um evento numa grade —; `li` dentro de uma lista. Padrão `div`. |

Aceita também: `React.HTMLAttributes<HTMLElement>`.

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--border` | #E5E5E5 | `border-border` |
| `--border-interactive` | #8C8C8C | `border-border-interactive` |
| `--card` | #FFFFFF | `bg-card` |
| `--card-foreground` | #1A1A1A | `text-card-foreground` |
| `--foreground` | #1A1A1A | `text-ink` |
| `--muted` | #F4F6F9 | `bg-muted` |
| `--muted-foreground` | #595959 | `text-muted-foreground` |

## Acessibilidade

### Teclado

| Tecla | Faz |
| --- | --- |
| Tab | No cartão clicável, uma parada: o `CardLink` do título, e o anel acende no cartão inteiro — conferido no teste da ficha. Cartão sem link não recebe foco. |
| Enter | Segue o link do cartão. |

### Leitor de tela

- O Card é um `<div>` sem papel: quem dá estrutura é o título (`CardTitle`, um cabeçalho).
- No cartão clicável, o nome do link é o que o leitor diz — faça dele o título, não "Saiba mais".

### O que sustenta o estado

Usa os padrões: estatico. Falta ouvir com leitor de tela: estatico.

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/atoms/Card.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-card--docs | Disponível |
| Teste de acessibilidade | axe em `npm run test` | No gate de todo commit |
| Leitor de tela | Passada da E33 | Falta ouvir |
| Design | Figma | Desativado até a Fase 2 |

### Histórico

- `0298af8` 2026-09-30 — E147: fechamento da Entrega 11 — REPORT.md, verificação cross-agent e o gate estático estrito
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/atoms/Card.tsx