# Card

Contêiner para agrupar informações relacionadas.

> Documentação do Sinapse DS. Snippets shadcn usam os componentes do seu projeto (`@/components/ui/*`); snippets HTML usam as classes `itps-*` do CSS Sinapse (`/css/<versão>/`, veja `/comecar.md`). Componentes do site de documentação não fazem parte do DS.

- Categoria: Layout
- Status: stable

## Em cada stack

- HTML e Astro: Classes `itps-*` do CSS Sinapse, com todas as variantes desta página.
- React e Vue: Componentes padrão do shadcn (`card`) com o tema Sinapse: cores, fonte e raio vêm do tema, e as variantes `itps-*` desta página existem só no HTML.

**React/Next (shadcn/ui)**

```tsx
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@/components/ui/card'

export function CardExample() {
  return (
    <Card className="w-[350px]">
      <CardHeader>
        <CardTitle>Relatório mensal</CardTitle>
        <CardDescription>Maio de 2026</CardDescription>
        <CardAction>
          <span className="text-sm font-medium text-primary">Pronto</span>
        </CardAction>
      </CardHeader>
      <CardContent>
        <p className="text-sm text-muted-foreground">
          Indicadores consolidados e liberados para revisão.
        </p>
      </CardContent>
      <CardFooter>
        <p className="text-xs text-muted-foreground">Atualizado hoje</p>
      </CardFooter>
    </Card>
  )
}
```

**Vue 3/Nuxt 4 (shadcn-vue)**

```vue
<script setup lang="ts">
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@/components/ui/card'
</script>

<template>
  <Card class="w-[350px]">
    <CardHeader>
      <CardTitle>Relatório mensal</CardTitle>
      <CardDescription>Maio de 2026</CardDescription>
      <CardAction>
        <span class="text-sm font-medium text-primary">Pronto</span>
      </CardAction>
    </CardHeader>
    <CardContent>
      <p class="text-sm text-muted-foreground">
        Indicadores consolidados e liberados para revisão.
      </p>
    </CardContent>
    <CardFooter>
      <p class="text-xs text-muted-foreground">Atualizado hoje</p>
    </CardFooter>
  </Card>
</template>
```

**HTML (copy-first)**

```html
<div class="itps-card">
  <div class="flex items-start justify-between gap-4">
    <div>
      <h3 class="text-lg font-semibold text-foreground">Relatório mensal</h3>
      <p class="mt-1 text-sm text-muted-foreground">Maio de 2026</p>
    </div>
    <span class="itps-tag itps-tag--success itps-tag--sm">Pronto</span>
  </div>
  <p class="mt-4 text-sm text-muted-foreground">
    Indicadores consolidados e liberados para revisão.
  </p>
</div>
```

## Instalação

O comando instala o Card da sua stack com o tema Sinapse. Configure o registry uma vez por projeto em [Comece por aqui](/comecar).

**terminal · React/Next**

```sh
pnpm dlx shadcn@latest add @sinapse/card
```

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/card.json
```

Sem shadcn, não há instalação por componente: use o CSS Sinapse e as classes da API copy-first desta página.

## Uso

Em React/Next com shadcn/ui e Vue 3/Nuxt 4 com shadcn-vue, use `Card` e seus compostos para estruturar cabeçalho, conteúdo, ações e rodapé. A composição deixa claro onde ficam título, descrição e ação.

Para HTML ou wrappers finos, use `itps-card` quando precisar de uma superfície neutra copy-first. Card não cria hierarquia interna; use heading, texto, Tag, Avatar ou Button conforme o conteúdo exigir.

## Exemplos

### Estrutura

| Peça | React/Next e Vue 3/Nuxt 4 | HTML |
|------|--------------------------|------|
| Contêiner | `Card` | `itps-card` |
| Cabeçalho | `CardHeader` | layout interno livre |
| Título | `CardTitle` | heading sem classe obrigatória |
| Descrição | `CardDescription` | texto de apoio |
| Ação | `CardAction` | Button, Link ou Tag conforme o caso |
| Conteúdo | `CardContent` | corpo do card |
| Rodapé | `CardFooter` | bloco final opcional |

### Variantes

Use a variante base para superfície com borda. `itps-card--elevated` adiciona sombra; `itps-card--flat` remove a borda visual e o padding para encaixar o conteúdo em layouts densos.

**HTML (copy-first)**

```html
<div class="grid w-full grid-cols-1 gap-3 md:grid-cols-3">
  <div class="itps-card itps-card--flat">
    <span class="text-sm text-foreground">Plano</span>
  </div>

  <div class="itps-card">
    <span class="text-sm text-foreground">Base</span>
  </div>

  <div class="itps-card itps-card--elevated">
    <span class="text-sm text-foreground">Elevado</span>
  </div>
</div>
```

## API copy-first

| Classe | Uso |
|--------|-----|
| `itps-card` | Superfície base com borda, fundo `card` e padding. |
| `itps-card--elevated` | Card com sombra para destaque moderado. |
| `itps-card--flat` | Remove borda visual e padding para composição interna. |

## Acessibilidade

Use `<div>` para agrupamento visual sem ação. Quando o bloco inteiro precisar navegar, prefira `Feature Card` ou um `Link` claro dentro do conteúdo. Evite colocar vários controles primários dentro de um card pequeno; isso torna a varredura e o foco mais difíceis.