@etus/ui 0.1.0

package/src/components/layout/Card/README.md

@@ -0,0 +1,994 @@
+# Card
+
+## Visão Geral
+
+O **Card** é um container fundamental do Design System ETUS, usado para agrupar conteúdo relacionado em uma unidade visual coesa. Como elemento de layout (molecule), serve de base para apresentar informações, ações e mídia de forma organizada e hierárquica.
+
+### Casos de Uso
+
+- Exibição de conteúdo em listas e grids (produtos, artigos, usuários)
+- Containers para formulários e configurações
+- Dashboards e widgets de informação
+- Preview de conteúdo com ações rápidas
+- Agrupamento de informações relacionadas
+
+### Classificação
+
+**Categoria:** Layout (Molecule)
+**Dependências:** `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Container padrão com borda e sombra sutil | `border`, `shadow-sm` |
+| `elevated` | Destaque visual com sombra pronunciada | `border`, `shadow-lg`, `hover:shadow-xl` |
+| `outlined` | Baixa ênfase, apenas borda | `border-2`, `shadow-none` |
+| `ghost` | Mínima ênfase, sem borda ou sombra | `border-none`, `shadow-none`, `bg-transparent` |
+
+### Estrutura de Compound Components
+
+O Card usa compound components para organização semântica:
+
+| Componente | Propósito | data-slot |
+|------------|-----------|-----------|
+| `Card` | Container principal | `card` |
+| `CardHeader` | Área de cabeçalho com grid para título e ações | `card-header` |
+| `CardTitle` | Título principal | `card-title` |
+| `CardDescription` | Descrição ou subtítulo | `card-description` |
+| `CardAction` | Área de ações no header (botões, menus) | `card-action` |
+| `CardContent` | Conteúdo principal | `card-content` |
+| `CardFooter` | Rodapé para ações ou info adicional | `card-footer` |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparência base conforme variante |
+| Hover (elevated) | `hover:shadow-xl` | Aumenta sombra com transição |
+| Interactive | `role="button"` + `tabIndex={0}` | Card clicável com focus ring |
+| Disabled | `opacity-50 pointer-events-none` | 50% opacidade, sem interação |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--card                 /* Fundo do card */
+--card-foreground      /* Cor do texto */
+--muted-foreground     /* Cor da descrição */
+--border               /* Cor da borda */
+
+/* Espaçamento */
+py-6                   /* Padding vertical do card */
+px-6                   /* Padding horizontal dos sub-componentes */
+gap-6                  /* Gap entre seções do card */
+gap-2                  /* Gap no header grid */
+
+/* Tipografia */
+font-semibold          /* Título */
+text-sm                /* Descrição */
+
+/* Bordas */
+rounded-xl             /* Border radius do card */
+
+/* Sombras */
+shadow-sm              /* Default */
+shadow-lg              /* Elevated */
+
+/* Transições */
+transition-shadow      /* Elevated hover */
+```
+
+### data-slot
+
+```html
+<div data-slot="card">
+  <div data-slot="card-header">
+    <div data-slot="card-title">...</div>
+    <div data-slot="card-description">...</div>
+    <div data-slot="card-action">...</div>
+  </div>
+  <div data-slot="card-content">...</div>
+  <div data-slot="card-footer">...</div>
+</div>
+```
+
+---
+
+## API
+
+### Card Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "elevated" \| "outlined" \| "ghost"` | `"default"` | Estilo visual do card |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo (compound components) |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### CardHeader Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Title, Description, Action |
+
+**Nota:** CardHeader usa CSS Grid com container query (`@container/card-header`) e detecta automaticamente a presença de CardAction via `has-data-[slot=card-action]:grid-cols-[1fr_auto]`.
+
+### CardTitle Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Texto do título |
+
+### CardDescription Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Texto da descrição |
+
+### CardAction Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Botões, menus, etc. |
+
+### CardContent Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo principal |
+
+### CardFooter Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Ações ou info adicional |
+
+### TypeScript
+
+```typescript
+import type { VariantProps } from "class-variance-authority"
+import type { ComponentProps } from "react"
+
+// Variants exportadas
+import { cardVariants } from "./Card.variants"
+
+// Props do componente principal
+interface CardProps extends ComponentProps<"div">, VariantProps<typeof cardVariants> {}
+
+// Props dos sub-componentes
+interface CardHeaderProps extends ComponentProps<"div"> {}
+interface CardTitleProps extends ComponentProps<"div"> {}
+interface CardDescriptionProps extends ComponentProps<"div"> {}
+interface CardActionProps extends ComponentProps<"div"> {}
+interface CardContentProps extends ComponentProps<"div"> {}
+interface CardFooterProps extends ComponentProps<"div"> {}
+
+// Tipo derivado para variantes
+type CardVariant = NonNullable<VariantProps<typeof cardVariants>["variant"]>
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|
+| **Variantes** | 4 | 1 | 1 | 4 | 1 | 1 | 3 | 4 | - | - | 1 | 2 |
+| **CVA/variants** | ✓ | ✓ | - | - | - | - | - | ✓ | - | - | - | - |
+| **Compound Components** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | - | - | - | - | - |
+| **Header** | ✓ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Footer** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | - |
+| **Action area** | ✓ | ✓ | - | - | ✓ | - | ✓ | - | - | - | - | - |
+| **Cover/Media** | - | - | - | - | ✓ | - | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Section** | - | - | - | - | - | ✓ | ✓ | ✓ | - | - | - | - |
+| **isPressable** | - | - | - | - | ✓ | - | ✓ | ✓ | - | - | - | - |
+| **isBlurred** | - | - | - | - | - | - | - | ✓ | - | - | - | - |
+| **Loading** | - | - | - | - | - | - | ✓ | - | - | - | - | - |
+| **Hoverable** | - | - | - | - | - | - | ✓ | - | - | - | - | - |
+| **Container Query** | ✓ | - | - | - | - | - | - | - | - | - | - | - |
+
+#### Comparativo de Variantes por Design System
+
+| Design System | Variantes Disponíveis |
+|---------------|----------------------|
+| **ETUS** | `default`, `elevated`, `outlined`, `ghost` |
+| **Shadcn/ui** | Default (sem variantes explícitas) |
+| **Chakra UI** | `elevated`, `outline`, `filled`, `unstyled` |
+| **MUI** | Default (customização via `sx` e `elevation`) |
+| **Mantine** | Default (herda de Paper: `shadow`, `radius`, `withBorder`) |
+| **Ant Design** | `default`, `bordered` + `size` (default, small) |
+| **NextUI** | `shadow` levels, `isBlurred`, `isFooterBlurred` |
+| **Fluent UI** | Default (customização via tokens) |
+| **Carbon** | `default`, `clickable` |
+
+#### Comparativo de Sub-componentes
+
+| Sub-componente | ETUS | Shadcn | Chakra | MUI | Mantine | AntD | NextUI | Fluent |
+|----------------|:----:|:------:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| **Header** | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **Title** | ✓ | ✓ | - | - | - | `Meta` | - | ✓ |
+| **Description** | ✓ | ✓ | - | `subheader` | - | `Meta` | - | ✓ |
+| **Action** | ✓ | ✓ | - | `action` | - | `extra` | - | - |
+| **Content** | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | - |
+| **Footer** | ✓ | ✓ | ✓ | `Actions` | `Section` | `actions` | ✓ | ✓ |
+| **Media/Cover** | - | - | - | ✓ | - | ✓ | ✓ | ✓ |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `role="article"` | Quando card representa conteúdo independente |
+| `role="button"` | Quando card é clicável (interativo) |
+| `role="listitem"` | Quando card está em uma lista |
+| `aria-label` | Descrição para cards sem título visível |
+| `aria-labelledby` | Referência ao CardTitle quando presente |
+| `aria-describedby` | Referência ao CardDescription quando presente |
+
+### Suporte a Teclado
+
+| Tecla | Ação |
+|-------|------|
+| `Tab` | Move foco para/do card (se interativo) |
+| `Enter` | Ativa card interativo |
+| `Space` | Ativa card interativo |
+
+### Focus Management
+
+```tsx
+// Card interativo com focus visible
+<Card
+  role="button"
+  tabIndex={0}
+  className="focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+  onClick={handleClick}
+>
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (mínimo 4.5:1):
+
+| Elemento | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| Card | `--card-foreground` | `--card` | ≥ 4.5:1 |
+| Description | `--muted-foreground` | `--card` | ≥ 4.5:1 |
+| Border | `--border` | `--card` | ≥ 3:1 |
+
+### Screen Readers
+
+- Cards devem ter contexto semântico claro via `role` apropriado
+- Usar `aria-labelledby` para associar título ao card
+- Evitar cards completamente clicáveis sem texto descritivo
+- Para cards em lista, usar estrutura `<ul>` + `<li>` com `role="list"` e `role="listitem"`
+
+### Reduced Motion
+
+```css
+/* Variante elevated respeita preferência do usuário */
+@media (prefers-reduced-motion: reduce) {
+  [data-slot="card"] {
+    transition: none;
+  }
+}
+```
+
+### Comparativo A11y (12 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|
+| **Semantic HTML** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ |
+| **Keyboard nav** | ~ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ |
+| **Focus visible** | ~ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ |
+| **aria-labelledby** | ~ | ✓ | - | ✓ | - | ~ | ✓ | - | - | ✓ | ✓ | ✓ |
+| **role support** | ~ | ✓ | - | ✓ | - | ~ | ✓ | - | - | ✓ | ✓ | ✓ |
+| **Reduced motion** | ~ | ✓ | - | - | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado/N/A
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@etus/ui"
+
+function Example() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Card Title</CardTitle>
+        <CardDescription>Card description goes here.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p>Card content goes here.</p>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+### Variantes
+
+```tsx
+<Card variant="default">Default card with border and subtle shadow</Card>
+
+<Card variant="elevated">Elevated card with prominent shadow</Card>
+
+<Card variant="outlined">Outlined card with thicker border</Card>
+
+<Card variant="ghost">Ghost card without border or background</Card>
+```
+
+### Com Header e Footer
+
+```tsx
+import { Button } from "@etus/ui"
+
+<Card>
+  <CardHeader>
+    <CardTitle>Criar Projeto</CardTitle>
+    <CardDescription>Configure seu novo projeto.</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <form>
+      <input placeholder="Nome do projeto" />
+    </form>
+  </CardContent>
+  <CardFooter>
+    <Button variant="outline">Cancelar</Button>
+    <Button>Criar</Button>
+  </CardFooter>
+</Card>
+```
+
+### Com Ação no Header
+
+```tsx
+import { Button } from "@etus/ui"
+import { MoreHorizontal } from "lucide-react"
+
+<Card>
+  <CardHeader>
+    <CardTitle>Configurações</CardTitle>
+    <CardDescription>Gerencie suas preferências.</CardDescription>
+    <CardAction>
+      <Button variant="ghost" size="icon">
+        <MoreHorizontal />
+      </Button>
+    </CardAction>
+  </CardHeader>
+  <CardContent>
+    {/* Conteúdo */}
+  </CardContent>
+</Card>
+```
+
+### Card Interativo (Clicável)
+
+```tsx
+<Card
+  variant="elevated"
+  role="button"
+  tabIndex={0}
+  className="cursor-pointer focus-visible:ring-2 focus-visible:ring-ring"
+  onClick={() => console.log("Card clicked")}
+  onKeyDown={(e) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault()
+      console.log("Card activated via keyboard")
+    }
+  }}
+>
+  <CardHeader>
+    <CardTitle>Clique para expandir</CardTitle>
+    <CardDescription>Este card é interativo</CardDescription>
+  </CardHeader>
+</Card>
+```
+
+### Card com Imagem
+
+```tsx
+<Card>
+  <img
+    src="/placeholder.jpg"
+    alt="Placeholder"
+    className="w-full h-48 object-cover rounded-t-xl"
+  />
+  <CardHeader>
+    <CardTitle>Card com Imagem</CardTitle>
+    <CardDescription>Imagem no topo do card.</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Conteúdo abaixo da imagem.</p>
+  </CardContent>
+</Card>
+```
+
+### Card em Grid
+
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+  {items.map((item) => (
+    <Card key={item.id}>
+      <CardHeader>
+        <CardTitle>{item.title}</CardTitle>
+        <CardDescription>{item.description}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p>{item.content}</p>
+      </CardContent>
+    </Card>
+  ))}
+</div>
+```
+
+### Card com Bordas Customizadas
+
+```tsx
+// Header com borda inferior
+<Card>
+  <CardHeader className="border-b">
+    <CardTitle>Seção com Borda</CardTitle>
+  </CardHeader>
+  <CardContent>Conteúdo</CardContent>
+  <CardFooter className="border-t">Footer</CardFooter>
+</Card>
+```
+
+### Card em Lista Acessível
+
+```tsx
+<ul role="list" className="space-y-4">
+  {items.map((item) => (
+    <li key={item.id} role="listitem">
+      <Card>
+        <CardHeader>
+          <CardTitle>{item.title}</CardTitle>
+        </CardHeader>
+        <CardContent>{item.content}</CardContent>
+      </Card>
+    </li>
+  ))}
+</ul>
+```
+
+### Responsividade
+
+```tsx
+// Card responsivo com largura adaptável
+<Card className="w-full max-w-sm md:max-w-md lg:max-w-lg">
+  <CardHeader>
+    <CardTitle>Card Responsivo</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm md:text-base">
+      Conteúdo que se adapta ao tamanho da tela.
+    </p>
+  </CardContent>
+</Card>
+```
+
+### Composição com Formulário
+
+```tsx
+import { useForm } from "react-hook-form"
+import { Button, Input, Label } from "@etus/ui"
+
+function LoginCard() {
+  const { handleSubmit, register } = useForm()
+
+  return (
+    <Card className="w-full max-w-sm">
+      <CardHeader>
+        <CardTitle>Login</CardTitle>
+        <CardDescription>Entre com suas credenciais.</CardDescription>
+      </CardHeader>
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <CardContent className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="email">Email</Label>
+            <Input id="email" type="email" {...register("email")} />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="password">Senha</Label>
+            <Input id="password" type="password" {...register("password")} />
+          </div>
+        </CardContent>
+        <CardFooter>
+          <Button type="submit" className="w-full">Entrar</Button>
+        </CardFooter>
+      </form>
+    </Card>
+  )
+}
+```
+
+### Card de Perfil com Avatar
+
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from "@etus/ui"
+
+function ProfileCard() {
+  return (
+    <Card className="w-80">
+      <CardHeader className="flex flex-row items-center gap-4">
+        <Avatar>
+          <AvatarImage src="/avatar.jpg" alt="João Silva" />
+          <AvatarFallback>JS</AvatarFallback>
+        </Avatar>
+        <div>
+          <CardTitle>João Silva</CardTitle>
+          <CardDescription>Desenvolvedor Frontend</CardDescription>
+        </div>
+      </CardHeader>
+      <CardContent>
+        <p className="text-sm text-muted-foreground">
+          Especialista em React e TypeScript com 5 anos de experiência.
+        </p>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+### Card de Estatísticas/KPI
+
+```tsx
+import { TrendingUp } from "lucide-react"
+
+function StatsCard() {
+  return (
+    <Card>
+      <CardHeader className="flex flex-row items-center justify-between pb-2">
+        <CardTitle className="text-sm font-medium text-muted-foreground">
+          Receita Total
+        </CardTitle>
+        <TrendingUp className="size-4 text-green-500" />
+      </CardHeader>
+      <CardContent>
+        <div className="text-2xl font-bold">R$ 45.231,89</div>
+        <p className="text-xs text-muted-foreground">
+          <span className="text-green-500">+20.1%</span> em relação ao mês anterior
+        </p>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+### Card com Loading State
+
+```tsx
+import { Skeleton } from "@etus/ui"
+
+function LoadingCard() {
+  return (
+    <Card>
+      <CardHeader>
+        <Skeleton className="h-6 w-32" />
+        <Skeleton className="h-4 w-48 mt-2" />
+      </CardHeader>
+      <CardContent>
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-3/4 mt-2" />
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Card.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "./Card"
+
+describe("Card", () => {
+  it("renders children correctly", () => {
+    render(<Card>Card Content</Card>)
+    expect(screen.getByText("Card Content")).toBeInTheDocument()
+  })
+
+  it("applies variant classes", () => {
+    render(<Card variant="elevated">Elevated</Card>)
+    expect(screen.getByText("Elevated")).toHaveClass("shadow-lg")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Card data-testid="card">Content</Card>)
+    expect(screen.getByTestId("card")).toHaveAttribute("data-slot", "card")
+  })
+
+  it("merges custom className", () => {
+    render(<Card className="custom-class">Test</Card>)
+    expect(screen.getByText("Test")).toHaveClass("custom-class")
+  })
+})
+```
+
+### Testes de Compound Components
+
+```tsx
+describe("Card compound components", () => {
+  it("renders all sub-components correctly", () => {
+    render(
+      <Card>
+        <CardHeader>
+          <CardTitle>Title</CardTitle>
+          <CardDescription>Description</CardDescription>
+          <CardAction>Action</CardAction>
+        </CardHeader>
+        <CardContent>Content</CardContent>
+        <CardFooter>Footer</CardFooter>
+      </Card>
+    )
+
+    expect(screen.getByText("Title")).toBeInTheDocument()
+    expect(screen.getByText("Description")).toBeInTheDocument()
+    expect(screen.getByText("Action")).toBeInTheDocument()
+    expect(screen.getByText("Content")).toBeInTheDocument()
+    expect(screen.getByText("Footer")).toBeInTheDocument()
+  })
+
+  it("each sub-component has correct data-slot", () => {
+    render(
+      <Card data-testid="card">
+        <CardHeader data-testid="header">
+          <CardTitle data-testid="title">Title</CardTitle>
+          <CardDescription data-testid="description">Description</CardDescription>
+          <CardAction data-testid="action">Action</CardAction>
+        </CardHeader>
+        <CardContent data-testid="content">Content</CardContent>
+        <CardFooter data-testid="footer">Footer</CardFooter>
+      </Card>
+    )
+
+    expect(screen.getByTestId("card")).toHaveAttribute("data-slot", "card")
+    expect(screen.getByTestId("header")).toHaveAttribute("data-slot", "card-header")
+    expect(screen.getByTestId("title")).toHaveAttribute("data-slot", "card-title")
+    expect(screen.getByTestId("description")).toHaveAttribute("data-slot", "card-description")
+    expect(screen.getByTestId("action")).toHaveAttribute("data-slot", "card-action")
+    expect(screen.getByTestId("content")).toHaveAttribute("data-slot", "card-content")
+    expect(screen.getByTestId("footer")).toHaveAttribute("data-slot", "card-footer")
+  })
+})
+```
+
+### Testes de Interação
+
+```tsx
+import userEvent from "@testing-library/user-event"
+import { vi } from "vitest"
+
+describe("Card interactions", () => {
+  it("clickable card can receive click handler", async () => {
+    const user = userEvent.setup()
+    const handleClick = vi.fn()
+
+    render(<Card onClick={handleClick}>Click me</Card>)
+    await user.click(screen.getByText("Click me"))
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it("interactive card can be activated with Enter key", async () => {
+    const user = userEvent.setup()
+    const handleKeyDown = vi.fn()
+
+    render(
+      <Card
+        data-testid="card"
+        role="button"
+        tabIndex={0}
+        onKeyDown={handleKeyDown}
+      >
+        Interactive
+      </Card>
+    )
+
+    const card = screen.getByTestId("card")
+    card.focus()
+    await user.keyboard("{Enter}")
+
+    expect(handleKeyDown).toHaveBeenCalled()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Card accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Card>
+        <CardHeader>
+          <CardTitle>Title</CardTitle>
+          <CardDescription>Description</CardDescription>
+        </CardHeader>
+        <CardContent>Content</CardContent>
+        <CardFooter>Footer</CardFooter>
+      </Card>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations with all variants", async () => {
+    const { container } = render(
+      <div>
+        <Card variant="default">Default</Card>
+        <Card variant="elevated">Elevated</Card>
+        <Card variant="outlined">Outlined</Card>
+        <Card variant="ghost">Ghost</Card>
+      </div>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("interactive card with role button has no violations", async () => {
+    const { container } = render(
+      <Card
+        aria-label="Clickable card"
+        role="button"
+        tabIndex={0}
+        onClick={() => {}}
+      >
+        <CardContent>Click me</CardContent>
+      </Card>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("card in list context has no violations", async () => {
+    const { container } = render(
+      <ul role="list">
+        <li role="listitem">
+          <Card>
+            <CardContent>Item 1</CardContent>
+          </Card>
+        </li>
+        <li role="listitem">
+          <Card>
+            <CardContent>Item 2</CardContent>
+          </Card>
+        </li>
+      </ul>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
+```
+
+### Testes de Styling
+
+```tsx
+describe("Card styling", () => {
+  it("CardHeader applies container query class", () => {
+    render(<CardHeader data-testid="header">Header</CardHeader>)
+    expect(screen.getByTestId("header")).toHaveClass("@container/card-header")
+  })
+
+  it("CardAction positions correctly in header grid", () => {
+    render(<CardAction data-testid="action">Action</CardAction>)
+    const action = screen.getByTestId("action")
+    expect(action).toHaveClass("col-start-2", "row-span-2")
+  })
+
+  it("CardTitle has font-semibold", () => {
+    render(<CardTitle data-testid="title">Title</CardTitle>)
+    expect(screen.getByTestId("title")).toHaveClass("font-semibold")
+  })
+
+  it("CardDescription has muted foreground color", () => {
+    render(<CardDescription data-testid="desc">Description</CardDescription>)
+    expect(screen.getByTestId("desc")).toHaveClass("text-muted-foreground")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### Prioridade Alta
+
+#### `CardMedia` / `CardCover`
+
+Componente dedicado para imagens e mídia.
+
+```tsx
+// Proposta de API
+<Card>
+  <CardMedia src="/image.jpg" alt="Description" aspectRatio="16/9" />
+  <CardHeader>
+    <CardTitle>Card com Mídia</CardTitle>
+  </CardHeader>
+</Card>
+```
+
+**Referências:** MUI (`CardMedia`), AntD (`cover`), NextUI (`CardImage`)
+
+#### `size` prop
+
+Variantes de tamanho para padding e tipografia.
+
+```tsx
+// Proposta de API
+interface CardProps {
+  size?: "sm" | "default" | "lg"
+}
+
+// Uso
+<Card size="sm">Compact card</Card>
+```
+
+**Referências:** AntD (`size`), Chakra UI (`size`)
+
+### Prioridade Média
+
+#### `isPressable` / `isHoverable`
+
+Props para cards interativos com estados visuais automáticos.
+
+```tsx
+// Proposta de API
+interface CardProps {
+  isPressable?: boolean
+  isHoverable?: boolean
+}
+
+// Uso
+<Card isPressable onClick={handleClick}>
+  Pressable card
+</Card>
+```
+
+**Referências:** NextUI (`isPressable`), AntD (`hoverable`)
+
+#### `loading` state
+
+Estado de carregamento com skeleton automático.
+
+```tsx
+// Proposta de API
+interface CardProps {
+  loading?: boolean
+}
+
+// Uso
+<Card loading>
+  <CardHeader>
+    <CardTitle>Loading content...</CardTitle>
+  </CardHeader>
+</Card>
+```
+
+**Referências:** AntD (`loading`)
+
+### Prioridade Baixa
+
+#### `CardSection`
+
+Para cards com múltiplas seções full-bleed.
+
+```tsx
+// Proposta de API
+<Card>
+  <Card.Section inheritPadding>
+    <img src="/banner.jpg" />
+  </Card.Section>
+  <CardContent>Content</CardContent>
+</Card>
+```
+
+**Referências:** Mantine (`Card.Section`), NextUI (`CardDivider`)
+
+#### `isBlurred` / `isFooterBlurred`
+
+Efeitos de blur para cards sobre fundos dinâmicos.
+
+```tsx
+// Proposta de API
+<Card isBlurred isFooterBlurred>
+  Content with blur effect
+</Card>
+```
+
+**Referências:** NextUI (`isBlurred`, `isFooterBlurred`)
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `CardMedia` | ✅ Implementar | 5+ DS implementam, comum em UIs |
+| `size` | ✅ Implementar | Útil para variação de densidade |
+| `isPressable` | ⚠️ Avaliar | Pode ser feito via className |
+| `loading` | ⚠️ Avaliar | Skeleton genérico pode ser melhor |
+| `CardSection` | ❌ Evitar por ora | Complexidade, usar className |
+| `isBlurred` | ❌ Evitar | Caso de uso específico |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Card](https://ui.shadcn.com/docs/components/card) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [Card](https://www.radix-ui.com/themes/docs/components/card) | [radix-ui/themes](https://github.com/radix-ui/themes) |
+| **React Aria** | - (sem Card dedicado) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Chakra UI** | [Card](https://chakra-ui.com/docs/components/card) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Card](https://mui.com/material-ui/react-card/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Card](https://mantine.dev/core/card/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Card](https://ant.design/components/card) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Card](https://heroui.com/docs/components/card) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Headless UI** | - (sem Card) | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **Ariakit** | - (sem Card) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Fluent UI** | [Card](https://react.fluentui.dev/?path=/docs/components-card-card--docs) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [Card](https://carbondesignsystem.com/components/card/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [Card](https://blueprintjs.com/docs/#core/components/card) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | [Card](https://primereact.org/card/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Disclosure Card](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - article Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article)
+- [Inclusive Components - Cards](https://inclusive-components.design/cards/)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Tailwind Container Queries](https://tailwindcss.com/docs/container-queries)