Pular para o conteúdo

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.

/padroes/erros.mdo mesmo arquivo que a skill entrega ao agente

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

  • Toast nã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

  • FieldError e o FormField: 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, DataTable e as peças de consulta com isError, errorTitle, errorMessage e onRetry: o erro de carga no lugar do conteúdo. Quando ele toma a página ou a seção, errorIllustration leva o desenho (ServerError, ou o Bacalhau triste em produto da RivoCode) e troca o aviso pelo Result de perigo.
  • Result com tone="danger" e illustration: 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 reset mora no caminho do sucesso, e nunca no catch nem no onError.
  • 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, stack ou 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 ganha aria-invalid: o FormField já faz.
  • No envio que falha, o foco vai ao FormErrorSummary ou ao primeiro campo com erro, e não fica parado no botão.
  • O Alert de danger e warning sai com role="alert"; o erro de carga do QueryBoundary é 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.

Os blocos que o aplicam

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.