Erro

Comunicação de falhas do sistema ou de ações do usuário.

Guia de decisão — Qual estado de tela usar?

  • Carregando (Skeleton / Spinner): Use Skeleton ao carregar blocos ou páginas inteiras onde o formato do layout futuro já é conhecido; use Spinner para ações pontuais acionadas pelo usuário (botões salvando, envios). Não use Spinner ocupando a tela inteira se a estrutura da página puder ser antecipada com Skeleton.
  • Vazio (EmptyState): Use quando a requisição foi bem-sucedida (status 200), mas não há registros a exibir (busca sem resultados, tabela nova sem dados, filtros sem correspondência). Deve orientar a ação positiva (limpar filtros, criar primeiro item). Nunca use estado de erro para listas legitimamente vazias.
  • Erro de Carregamento (ErrorState): Use quando a requisição falhar (erro 500, timeout 504, rede offline) e houver possibilidade de recuperação pelo usuário via onRetry. Apresente mensagem clara em linguagem humana e botão de ação.
  • Erro de Formulário (FormField + ErrorSummary): Use para validação de dados de entrada do usuário antes ou após submissão. Indique o campo exato e agregue no ErrorSummary se houver múltiplos erros.
  • Aviso Contextual (Alert): Use para comunicar problemas não impeditivos ou avisos de sistema que não impedem a continuidade do fluxo.
  • Sem permissão (403): Apresente mensagem clara informando que o perfil não possui acesso ao recurso, oferecendo botão para voltar ou solicitar acesso ao gestor.

Boas práticas

  • Explicar o que aconteceu em linguagem simples, sem termos técnicos indecifráveis para o cidadão.
  • Indicar como resolver ou o que tentar em seguida.
  • Oferecer sempre ação de recuperação quando possível (tentar novamente, voltar ao início, contatar suporte).
  • Evitar culpar o usuário pela falha.

Anti-padrões

  • Não usar mensagens técnicas ou códigos HTTP puros sem explicação humana (ex.: apenas 'Erro 500').
  • Não mostrar erros genéricos sem contexto ou ação de retorno.
  • Não deixar o usuário sem caminho de recuperação ou travado em tela em branco.
  • Não usar estilo de erro vermelho para situações comuns de busca sem resultados (use EmptyState).

Acessibilidade

  • Anunciar o erro para leitores de tela com role="alert" e aria-live="assertive".
  • Garantir contraste mínimo WCAG AA (4.5:1 para texto normal) e não usar exclusivamente a cor vermelha para transmitir o significado do erro.
  • Manter o foco em local útil após o erro (ou direcionar para a mensagem de recuperação).

Exemplo interativo — Banner de erro

O que falhou, por quê e o que fazer agora — com ação de tentar novamente.