# Alert

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

Mensagem de aviso, informação, sucesso, atenção ou erro, com ícone, título opcional e o tipo dito em texto para quem ouve. Erro e atenção interrompem o leitor de tela; informação e sucesso esperam a pausa. Pode ter uma ação e um botão de fechar.

- Função: Estado e aviso
- Também chamado de: aviso, alerta, mensagem, notificação, banner de aviso
- Mora em: `app/components/molecules/Alert.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/Alert](https://phorte-design-system.vercel.app/styleguide/peca/Alert)
- Ficha no Storybook: [components-complex-alert](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-alert--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/Alert/0](https://phorte-design-system.vercel.app/previa/Alert/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 { Alert } from '@/app/components/molecules/Alert';

<Alert description={…}>…</Alert>
```

O `…` marca as props obrigatórias — ver *Propriedades*.

## Uso

### Variantes na ficha

1. [Interativo](https://phorte-design-system.vercel.app/previa/Alert/0)
2. [Variantes](https://phorte-design-system.vercel.app/previa/Alert/1)
3. [Sem título](https://phorte-design-system.vercel.app/previa/Alert/2)
4. [Dispensável](https://phorte-design-system.vercel.app/previa/Alert/3)
5. [Com ação](https://phorte-design-system.vercel.app/previa/Alert/4)
6. [Dentro de formulário](https://phorte-design-system.vercel.app/previa/Alert/5)

Para uma mensagem que diz respeito à página ou a uma seção inteira — o pagamento foi confirmado, a inscrição falhou, o prazo está perto.

### Quando não usar

Para o erro de um campo, use o FormField, que liga a mensagem ao campo. Para pedir uma decisão antes de seguir, o Modal. Para uma confirmação que some sozinha ("Salvo"), o aviso passageiro, não o Alert. Para uma mensagem do site inteiro, uma faixa no topo. Para um rótulo de uma palavra, o Badge.

### Faça

- Escolha a variante pela gravidade: `destructive` para erro, `warning` para atenção, `success` para concluído.
- Escreva o que aconteceu e o que fazer: "Não conseguimos processar o pagamento. Tente outro cartão."
- Passe um `role` próprio quando um sucesso precisar ser ouvido na hora.
- Seja breve: até três linhas. O que passar disso é página, não aviso.
- Dê uma `acao` quando houver o que fazer: "Gerar boleto", "Tentar de novo" (E62).
- Use `titleAs="h2"` (ou o nível certo) quando o alerta abre uma seção; o padrão é `p`, fora da navegação por títulos.

### Evite

- Alert de sucesso ou de informação inserido depois de uma ação: a região `status` criada junto com o texto pode não ser anunciada. Para o retorno de uma ação, o Aviso — a região dele já existe (E144).
- `destructive` e `warning` para mensagem que não é urgente: interrompem quem está ouvindo.
- Alerta dispensável com informação que a pessoa ainda vai precisar.
- Vários alertas empilhados — um por vez, o mais grave primeiro.
- Duas ações num aviso: aí é decisão, e decisão é Modal.

### Nota de uso

**Quando usar (E62):** para o que diz respeito à página ou ao formulário — e só um por vez, em até três linhas. Não para confirmação que some sozinha, nem para mensagem do site inteiro. O título é `p` por padrão (`titleAs` o faz cabeçalho), e a `acao` põe o que fazer a respeito num botão. Só erro e atenção usam `role="alert"`, que interrompe o leitor; informação e sucesso usam `role="status"`, que espera a pausa. Um `role` passado por prop vence — para um sucesso que aparece logo depois de uma ação, por exemplo. O tipo vem em texto para quem ouve ("Erro:", "Atenção:"…): a cor e o ícone não chegam lá.

### Anatomia

1. **Ícone** — Por variante (informação, visto, alerta, X), decorativo.
2. **Tipo em texto** — "Erro:", "Atenção:", "Sucesso:"… — só para o leitor de tela.
3. **Título** — Opcional, em negrito. `p` por padrão; `titleAs` escolhe o cabeçalho (E62).
4. **Descrição** — `text-sm`, obrigatória; aceita link e ênfase.
5. **Ação** — Com `acao`: Button `outline` pequeno embaixo do texto — ou link, com `href` (E62).
6. **Fechar** — Com `dismissible`: botão "Fechar alerta" de 44×44 no canto.

### Estados

| Estado | O que muda |
| --- | --- |
| Aviso | `default`: fundo `--muted`, `role="status"`. |
| Informação | `info`: fundo `--info-subtle`, texto `--info-strong`, `role="status"`. |
| Sucesso | `success`: fundo `--success-subtle`, texto `--success-strong`, `role="status"`. |
| Atenção | `warning`: fundo `--warning-subtle`, texto `--warning-strong`, `role="alert"`. |
| Erro | `destructive`: fundo `--destructive-subtle`, texto `--destructive-strong`, `role="alert"`. |
| Fechado | Depois do botão de fechar, o componente deixa de ser renderizado. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Aparece com `role="alert"` | O leitor de tela interrompe o que lia e anuncia. |
| Aparece com `role="status"` | O leitor anuncia na próxima pausa. |
| Fechar | Some, chama `onDismiss` e leva o foco a `retornarFocoPara` — ou, sem ela, ao próximo elemento focável depois do alerta (o anterior, se não houver) — medido no teste da ficha. |

### Relacionados

- [FormField](https://phorte-design-system.vercel.app/styleguide/md/FormField.md) — Erro de um campo, ligado a ele.
- [Modal](https://phorte-design-system.vercel.app/styleguide/md/Modal.md) — Para pedir uma decisão.
- [Badge](https://phorte-design-system.vercel.app/styleguide/md/Badge.md) — Estado em uma palavra.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `variant` | `'default' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | `'default'` | não | Variante do `cva`. |
| `title` | `React.ReactNode` | — | não |  |
| `titleAs` | `'p' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'p'` | não | O elemento do título (E62). Padrão `p`: o alerta não sabe em que nível da página está, e um cabeçalho no nível errado quebra a navegação por títulos — era `h5` fixo, que pulava três níveis sob um `h2`. Passe `h2`, `h3`… quando o alerta abre uma seção. |
| `description` | `React.ReactNode` | — | sim | Texto do aviso. Aceita link e ênfase (E62). |
| `acao` | `{ rotulo: string; onClick?: () => void; href?: string }` | — | não | O que fazer a respeito, num botão (E62): "Tentar de novo", "Ver boleto". Com `href`, vira link. Um só — duas ações num aviso viram decisão, e decisão é Modal. |
| `dismissible` | `boolean` | `false` | não |  |
| `onDismiss` | `() => void` | — | não |  |
| `retornarFocoPara` | `React.RefObject<HTMLElement \| null>` | — | não | Para onde o foco vai quando a pessoa fecha o alerta. Sem ele, vai para o próximo elemento focável depois do alerta (ou o anterior, se não houver) — nunca para o `<body>` (E102). |

Aceita também: `Omit<React.HTMLAttributes<HTMLDivElement>, 'title'>`.

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--foreground` | #1A1A1A | `bg-ink/5`, `text-ink` |
| `--border` | #E5E5E5 | `border-border` |
| `--destructive` | #BA0517 | `border-destructive/25` |
| `--destructive-strong` | #BA0517 | `text-destructive-strong` |
| `--destructive-subtle` | #F9EBEC | `bg-destructive-subtle` |
| `--info` | #1D345E | `border-info/25` |
| `--info-strong` | #142544 | `text-info-strong` |
| `--info-subtle` | #EDF0F5 | `bg-info-subtle` |
| `--muted` | #F4F6F9 | `bg-muted` |
| `--success` | #2E844A | `border-success/25` |
| `--success-strong` | #276F3E | `text-success-strong` |
| `--success-subtle` | #EEF5F1 | `bg-success-subtle` |
| `--warning` | #DD7A01 | `border-warning/25` |
| `--warning-strong` | #945201 | `text-warning-strong` |
| `--warning-subtle` | #FCF4EB | `bg-warning-subtle` |

## Acessibilidade

### Teclado

| Tecla | Faz |
| --- | --- |
| Tab | Leva o foco à ação, se houver, e depois a "Fechar alerta", com `dismissible`; sem os dois, o alerta não tem parada. |
| Enter / Espaço | Fecha o alerta — medido: ele some, `onDismiss` é chamado e o foco vai para o elemento seguinte. |

### Leitor de tela

- O tipo vai em texto escondido antes do conteúdo ("Erro: …"): a cor e o ícone não chegam a quem ouve.
- O anel de foco do botão de fechar é a cor do próprio texto do alerta (`ring-current`).

### 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/molecules/Alert.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-alert--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/molecules/Alert.tsx