# Aviso

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

Confirmação passageira de uma ação — "Inscrição salva", "Link copiado" —, no canto de baixo da tela, anunciada por região viva sem roubar o foco. Some sozinha em 6s, e o tempo para no hover e no foco; o erro não some sozinho.

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

<Aviso mensagem={…}>…</Aviso>
```

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

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/Aviso/0)
2. [Tipos](https://phorte-design-system.vercel.app/previa/Aviso/1)
3. [Com ação](https://phorte-design-system.vercel.app/previa/Aviso/2)
4. [Na página](https://phorte-design-system.vercel.app/previa/Aviso/3)

Logo depois de uma ação da pessoa, para confirmar que deu certo (ou avisar que falhou) sem tirá-la de onde está.

### Quando não usar

Para uma mensagem que diz respeito à página ou ao formulário e precisa ficar, use o Alert. Para pedir uma decisão, o Modal. Para o erro de um campo, o FormField.

### Faça

- Monte o `AvisosProvider` uma vez, no alto da página, e dispare com `useAvisos().avisar({ … })`.
- Escreva o que aconteceu, curto: "Inscrição salva." — e, se couber, uma `acao` que desfaz ("Desfazer").
- Use `tipo="erro"` para falha: vai para a região `alert` e fica até a pessoa fechar.

### Evite

- Informação que a pessoa ainda vai precisar: ela some.
- Mais de um aviso por ação. A pilha guarda no máximo três, e o mais antigo sai.
- Ação essencial só no aviso: quem não viu a tempo perde o caminho.

### Anatomia

1. **Ícone** — Por tipo (informação, visto, alerta, X), 20px, decorativo.
2. **Tipo em texto** — "Sucesso:", "Erro:"… só para o leitor, como no Alert.
3. **Título e mensagem** — Título opcional em negrito e a mensagem em `text-sm`.
4. **Ação** — Opcional: botão sublinhado de 44px de altura.
5. **Fechar** — "Fechar aviso", 44×44.

### Estados

| Estado | O que muda |
| --- | --- |
| Informação, sucesso, atenção, erro | Os pares tênue/forte do Alert (`--*-subtle` com `--*-strong`), 5,5:1 no mínimo. |
| Segurado | Com o ponteiro ou o foco em cima, o tempo para (`data-segurado`) — conferido no teste da ficha. |
| Entrando | Esmaece e sobe 8px em 300ms, só com movimento liberado. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Com ação | Não some sozinho, mesmo com `duracao` (E144): ação com cronômetro é limite de tempo (SC 2.2.1). Fica até alguém fechar — testado na ficha. |
| Esc | Com o foco num botão do aviso, dispensa o aviso (E144, guia de toasts do A11Y.md) — testado na ficha. |
| Tempo | Pelo tamanho do texto: 6 s no mínimo, cerca de 60 ms por caractere (E144; era 6 s para qualquer tamanho) — testado na ficha. |
| `avisar` com informação, sucesso ou atenção | Entra na região `status`, já montada, e é anunciado na próxima pausa — conferido no teste da ficha; o foco não se move. |
| `avisar` com erro | Entra na região `alert` e não some sozinho. |
| Fim do tempo | Some e chama `onFechar`; com o ponteiro em cima, espera — conferido no teste da ficha. |
| Quarto aviso | O mais antigo sai: no máximo três. |

### Relacionados

- [Alert](https://phorte-design-system.vercel.app/styleguide/md/Alert.md) — Mensagem que fica na página, junto do que comenta.
- [Modal](https://phorte-design-system.vercel.app/styleguide/md/Modal.md) — Para pedir uma decisão.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `tipo` | `'info' \| 'sucesso' \| 'atencao' \| 'erro'` | `'info'` | não | Variante do `cva`. |
| `mensagem` | `string` | — | sim | A mensagem, curta: "Inscrição salva." |
| `titulo` | `string` | — | não |  |
| `acao` | `{ rotulo: string; onClick: () => void }` | — | não | Uma ação só, que desfaz ou completa: "Desfazer", "Ver inscrição". |
| `onFechar` | `() => void` | — | não | Chamado pelo "Fechar aviso" e ao fim do tempo. |
| `duracao` | `number \| null` | — | não | Some sozinho depois deste tempo, em ms (padrão: pelo tamanho do texto, no mínimo 6 s). O **erro nunca some sozinho**: quem não viu a tempo perderia o que deu errado. **Aviso com ação também não** (E144): ação com cronômetro é limite de tempo (SC 2.2.1), que quem usa zoom ou leitor de tela perde — com `acao`, este valor é ignorado. O tempo para enquanto o ponteiro ou o foco estiverem no aviso. |

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

### Medidas

| Parte | Valor | Classe |
| --- | --- | --- |
| Largura, a partir de 768px (tablet) | 384px, no canto de baixo à direita | `md:w-96` |
| Tempo | 6s; o erro não some | `duracao` |

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--destructive` | #BA0517 | `border-destructive/25` |
| `--destructive-strong` | #BA0517 | `text-destructive-strong` |
| `--destructive-subtle` | #F9EBEC | `bg-destructive-subtle` |
| `--foreground` | #1A1A1A | `bg-ink/5` |
| `--info` | #1D345E | `border-info/25` |
| `--info-strong` | #142544 | `text-info-strong` |
| `--info-subtle` | #EDF0F5 | `bg-info-subtle` |
| `--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 | O aviso não rouba o foco; ele entra na ordem de Tab no fim da página — a ação e o "Fechar aviso". Conferido no teste da ficha. |
| Enter / Espaço | No "Fechar aviso", fecha; na ação, a executa — conferido no teste da ficha. |

### Leitor de tela

- As regiões vivas existem **antes** do aviso: região criada junto com a mensagem não é anunciada.
- O tempo cumpre a WCAG 2.2.1: para no hover e no foco, e o erro não tem tempo.
- O tipo vai em texto escondido ("Erro: …"): a cor e o ícone não chegam a quem ouve.

### O que sustenta o estado

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

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/molecules/Aviso.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-aviso--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

- `251416b` 2026-10-01 — E159: Testimonials — o vídeo toca dentro do cartão, YouTube e Vimeo
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/molecules/Aviso.tsx