Padrões de UX / Ação e resposta
O que fazer quando dá errado
O erro perto da causa, com o que fazer, sem apagar o que foi digitado, e os quatro finais de toda consulta.
O erro aparece perto da causa, diz o que fazer, e nunca apaga o que a pessoa digitou.
O problema
Erro que devolve o formulário vazio custa o trabalho inteiro de novo, e é o motivo mais comum de abandono. Erro que só diz "Algo deu errado" deixa a pessoa sem saber se espera, corrige ou liga para alguém. E a tela que desenha só o caminho feliz entrega metade, e a metade que falta é a que aparece no pior dia.
Quando usar
Em toda ação que pode falhar e em toda consulta. Toda consulta tem quatro finais, e cada um é uma decisão de fluxo, não só uma tela:
| Final | A decisão |
|---|---|
| carregando | esqueleto na forma do conteúdo que vem (espera.md) |
| erro | o que a pessoa faz agora, e se repetir resolve |
| vazio | é a primeira vez dela, ou o filtro não achou? São textos e ações diferentes |
| dados | o caminho feliz |
Quando não usar
Toastnão serve para erro que exige ação. Ele some. O que precisa continuar visível éAlert.- Página de erro inteira não serve para o pedaço que falhou. Se o resto da tela funciona, o erro fica no lugar do pedaço: experiencia-degradada.md.
- Vazio não é erro. Dado que não veio porque a consulta falhou não vira "Nenhum resultado".
As peças
FieldErrore oFormField: o erro de campo, no campo.FormErrorSummary: os erros do envio, no topo do formulário, com link para cada campo.Alert: o erro da operação, que fica na tela.QueryBoundary,DataTablee as peças de consulta comisError,errorTitle,errorMessageeonRetry: o erro de carga no lugar do conteúdo. Quando ele toma a página ou a seção,errorIllustrationleva o desenho (ServerError, ou o Bacalhau triste em produto da RivoCode) e troca o aviso peloResultde perigo.Resultcomtone="danger"eillustration: o fim de fluxo que falhou, e a página de erro (404, 403, 500, sem conexão).
Comportamento
- Preserve o que a pessoa digitou. O que foi digitado continua nos campos,
sempre. O
resetmora no caminho do sucesso, e nunca nocatchnem noonError. - O erro aparece perto da causa. Erro de campo no campo; erro da operação no
topo do formulário ou num
Alert; erro de carregamento no lugar do conteúdo que não veio. - Erro que se resolve repetindo ganha
onRetry. O que não se resolve repetindo ganha o caminho: quem procurar, ou o que corrigir. - Valide na saída do campo, não a cada tecla. Cobrar o CNPJ completo no terceiro dígito é acusar quem ainda está digitando. Depois do primeiro erro, o campo revalida a cada tecla, para o erro sumir assim que for corrigido.
- O botão de enviar não espera o formulário ficar válido. Desabilitado, ele não diz o que falta; habilitado, o clique mostra.
- O vazio de filtro devolve o filtro, e não oferece "criar": quem filtrou quer o filtro de volta.
<QueryBoundary
data={invoices.data}
isLoading={invoices.isPending}
isError={invoices.isError}
onRetry={invoices.refetch}
errorTitle="Não foi possível carregar as notas"
errorMessage="A prefeitura não respondeu. Tente de novo em alguns minutos."
skeleton={<InvoiceListSkeleton />}
>
{(list) => <InvoiceList invoices={list} />}
</QueryBoundary>
Texto
Duas frases, cada uma com um trabalho:
- O título diz o que falhou, nomeando o objeto: "Não foi possível carregar as notas". Nunca "Erro" nem "Algo deu errado".
- A descrição diz quem falhou e o que fazer: "A prefeitura não respondeu. Tente de novo em alguns minutos."
- Erro de campo diz o formato aceito: "Use o formato 00.000.000/0000-00", e não "Valor inválido".
- Nunca código de erro,
stackou nome de endpoint na tela. O que se oferece para copiar é o código do atendimento, que o suporte procura no log.
As formas completas estão em texto.md.
Acessibilidade
- O erro de campo se liga ao campo por
aria-describedby, e o campo ganhaaria-invalid: oFormFieldjá faz. - No envio que falha, o foco vai ao
FormErrorSummaryou ao primeiro campo com erro, e não fica parado no botão. - O
Alertdedangerewarningsai comrole="alert"; o erro de carga doQueryBoundaryé anunciado no lugar dele. - Cor nunca é o único sinal: o erro tem ícone e texto.
No celular e no nativo
No celular o erro de campo pode ficar embaixo do teclado: o foco no primeiro
campo com erro rola até ele. O QueryBoundary, o Alert, o Result e o
DataList do @rivocode/ui-native falam os mesmos nomes (isError,
errorTitle, errorMessage, onRetry), com o texto em string. O formulário
nativo entra por outro caminho: native.md.