Pular para o conteúdo

Padrões de UX / Dados e listas

Experiência degradada

O pedaço que falhou diz isso no lugar dele, o resto continua, e dado indisponível não vira vazio.

/padroes/experiencia-degradada.mdo mesmo arquivo que a skill entrega ao agente

Quando um pedaço da tela falha, ele diz isso no lugar dele, e o resto continua funcionando. Degrade, não bloqueie.

O problema

O gráfico de faturamento não carregou, e a página inteira vira "Algo deu errado", levando junto a lista de pedidos que tinha carregado. Ou o contrário: o serviço de estoque caiu, e a tela mostra "Nenhum produto", que a pessoa lê como verdade e vai repor o que não falta. Os dois erram no mesmo ponto: tratam o que falhou como se fosse a tela toda, ou como se fosse vazio.

Quando usar

Toda tela que junta mais de uma fonte: o painel com quatro consultas, o registro com o histórico de outro serviço, a listagem com o estoque de outro sistema, o app que perdeu a conexão no meio do uso. E toda falha parcial de um serviço de fora: a busca por CEP que não respondeu, o cálculo de frete fora do ar, o intermediador de pagamento lento.

Quando não usar

  • Quando nada da tela funciona sem o que falhou, a página de erro inteira é a resposta honesta: o Result do 500, do sem conexão ou da manutenção (erros.md).
  • Quando o dado que falhou é a condição da ação, a ação para: emitir a nota sem a resposta da prefeitura não é degradar, é emitir errado.
  • Quando a falha é da ação, e não da consulta, é o "deu errado" dos quatro momentos, no botão e no Alert: erros.md.

As peças

  • QueryBoundary por região, cada um com o seu isError, onRetry e o texto do pedaço.
  • DataTable e QueryBoundary com isRefetchError: o dado velho fica na tela com o aviso de que não está atualizado.
  • Alert no lugar do pedaço que falhou, com a frase do que continua.
  • Banner: a falha que atravessa a tela inteira (sem conexão, serviço de fora instável), uma faixa só, no topo.
  • useNetworkStatus: online ou offline.
  • Result com a ilustração Offline: quando nada funciona sem rede.

Comportamento

  • Cada região carrega e falha sozinha. Um QueryBoundary por consulta, e não um em volta da página. O gráfico que falhou mostra o erro do tamanho do gráfico, com "Tentar de novo", e a tabela ao lado segue com os dados dela.
  • Dado indisponível não vira estado vazio. "Não foi possível carregar o estoque" é uma coisa; "Nenhum produto em estoque" é outra, e trocar uma pela outra faz a pessoa agir sobre o que não é verdade. Na célula de uma tabela, o valor que não veio é "Indisponível", e não zero nem traço.
  • O dado velho fica, com a data. Revalidação que falhou mantém o que já estava, com "Atualizado às 14:02. Não foi possível atualizar agora." O isRefetchError com dado na mão faz isso nas peças de consulta.
  • A ação que depende do que falhou para; o resto não. Sem o frete, o carrinho continua editável, e só o "Finalizar compra" espera, com o motivo.
  • No máximo umas cinco mensagens por página. Se mais que isso falhou, a falha é de outra camada: troque as cinco por um Banner no topo ("O faturamento está fora do ar. Os números desta página podem estar desatualizados.") e deixe as regiões quietas, com o dado velho ou o espaço reservado.
  • Sem conexão, o que já está na tela continua legível, e o que precisa de rede diz isso no próprio controle. Ao voltar a conexão, a tela revalida sozinha, sem pedir para recarregar.
<div className="grid gap-8 lg:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]">
  <QueryBoundary
    data={revenue.data}
    isLoading={revenue.isPending}
    isError={revenue.isError}
    onRetry={revenue.refetch}
    errorTitle="Não foi possível carregar o faturamento"
    errorMessage="O resto do painel continua atualizado. Tente de novo em alguns minutos."
  >
    {(data) => <RevenueChart data={data} />}
  </QueryBoundary>
  <QueryBoundary
    data={orders.data}
    isLoading={orders.isPending}
    isError={orders.isError}
    onRetry={orders.refetch}
    errorTitle="Não foi possível carregar os pedidos"
    errorMessage="O sistema de pedidos não respondeu."
  >
    {(list) => <RecentOrders orders={list} />}
  </QueryBoundary>
</div>

Texto

  • O pedaço que falhou diz o que não veio e o que continua: "Não foi possível carregar o faturamento. O resto do painel continua atualizado."
  • Quem falhou, quando isso muda o que a pessoa faz: "O sistema da operadora não respondeu", "A busca por CEP está fora do ar. Preencha o endereço à mão."
  • O dado velho diz a hora: "Atualizado às 14:02".
  • O "Indisponível" da célula não é "0" nem "-": zero é um valor, e traço quer dizer "não se aplica".

Acessibilidade

  • Cada região que falha anuncia o erro dela uma vez, e não a página inteira em coro: cinco role="alert" disparando juntos atropelam o leitor de tela, e é mais um motivo do limite de cinco mensagens.
  • O "Tentar de novo" de cada região tem nome que diz qual: "Tentar carregar o faturamento de novo", ou o título da região ligado ao botão.
  • A região que falhou guarda o espaço dela, para a tela não pular quando a segunda tentativa der certo.

No celular e no nativo

No celular a conexão cai mais, e entra e sai no meio do uso. O useNetworkStatus é do web; no app, o estado da rede vem da biblioteca de rede do projeto. O QueryBoundary e o DataList do @rivocode/ui-native portam o isError, o isRefetchError e o onRetry com os mesmos nomes, e o Banner também existe lá. O que ficou guardado no aparelho continua aberto sem rede, e diz de quando é.

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.