Pular para o conteúdo

Padrões de UX / Ação e resposta

Espera

Quanto a espera dura decide o desenho: o botão em carga, o esqueleto da primeira carga e o progresso da espera longa.

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

A tela que espera mostra o que vem na forma do que vem, pelo tempo que a espera dura, e não tira do lugar o que a pessoa já estava lendo.

O problema

Toda ação e toda consulta têm um intervalo entre o pedido e a resposta, e é nele que a tela parece quebrada. Giro no meio da página esconde o que já estava certo; esqueleto que volta a cada filtro tira o ponto de leitura; um minuto de loading sem número parece travado, e a pessoa recarrega no meio do lote.

Quando usar

Em toda ação que faz requisição e em toda consulta que preenche a tela. O desenho muda com a duração:

Dura A tela Peça
até 1 s nada muda além do próprio controle: o clique responde, o dado troca quando chega o estado de active das peças
1 a 10 s a ação espera no botão, a consulta na forma do conteúdo loading, Skeleton, QueryBoundary
mais de 10 s quanto falta, o que está acontecendo, e um jeito de parar Progress com value e showValue, e um Button "Cancelar importação"

Quando não usar

  • Nada de giro de tela inteira, nem tarja que cobre a página: o Spinner é para o espaço pequeno onde o esqueleto não cabe, e não para a área de trabalho.
  • Nada de esqueleto depois da primeira carga. Trocar de página, de filtro ou de ordem segura a lista de antes com a barra fina do isFetching.
  • Ação que não é exceção não espera: otimista é o padrão, e a ação aparece feita na hora, pelo otimista.md. A espera no botão fica para dinheiro, efeito externo, o que não tem volta e o que depende da resposta.
  • Espera longa que pode seguir sozinha não prende a tela: vira aviso.

As peças

  • Button com loading: a ação espera no próprio botão, que recusa o segundo clique e anuncia ocupado.
  • Skeleton e o skeleton do QueryBoundary: a forma do conteúdo, com a largura da coluna.
  • DataTable e QueryBoundary com isLoading e isFetching: o primeiro é a primeira carga, o segundo a revalidação com o dado na mão. Com isFetching, os filhos do QueryBoundary vão numa caixa que veste o className, ou o classNames.content quando ele vem; numa coluna de chat ou de lista que precisa de altura, a altura vai em quem a caixa veste, senão a lista cresce e empurra o campo de escrever para fora.
  • Progress com value, max e showValue: o quanto, na espera longa.
  • toast.promise do useToast: a espera longa que sai da tela.

Comportamento

O esqueleto é da primeira carga

O esqueleto aparece quando não há nada na tela. Depois dela, a lista de antes fica até a nova chegar, com a barra fina do isFetching: piscar a tabela inteira a cada clique tira o ponto de leitura de quem estava comparando. Com TanStack Query, placeholderData: keepPreviousData segura a página de antes, e o isPending só fica verdadeiro na primeira vez.

const invoices = useQuery({
  queryKey: ['notas', page, filters],
  queryFn: () => listInvoices(page, filters),
  placeholderData: keepPreviousData,
})

<DataTable
  data={invoices.data?.items}
  rowCount={invoices.data?.total ?? 0}
  columns={COLUMNS}
  rowKey={(invoice) => invoice.id}
  isLoading={invoices.isPending}
  isFetching={invoices.isFetching}
  isError={invoices.isError}
  onRetry={invoices.refetch}
/>

O esqueleto tem a forma do conteúdo que vem, com a largura da coluna, para a tela não pular quando os dados chegarem. Retângulo cinza do tamanho da página inteira não é esqueleto, é giro com outra cor.

O que passa de 10 s mostra o quanto

Importar a planilha, emitir em lote, enviar arquivo grande: Progress com o número ("128 de 400 notas"), o nome do item da vez quando o total não se conhece, e a saída para cancelar.

<Progress label="Emitindo as notas do mês" value={done} max={total} showValue />

Quando a espera longa pode seguir sem a pessoa olhando, ela sai da tela e vira aviso: toast.promise troca o "Emitindo…" pelo resultado num aviso só.

A tela não some por baixo da pessoa

  • Não mova o que ela vai clicar. Conteúdo que chega depois entra abaixo do ponto de leitura, ou reserva o espaço desde o começo.
  • Ação que demora fica presa ao botão, com loading e o botão desabilitado, e nunca uma tarja que cobre a tela.
  • Confirmação não muda de lugar. O botão que confirma fica sempre no mesmo canto do rodapé, em todos os diálogos do produto.
  • Fechar uma folha ou um diálogo devolve o foco ao gatilho, senão o teclado recomeça do topo da página. As peças da casa já fazem isso; layout escrito à mão não.

Texto

  • O botão em espera continua dizendo a ação ("Emitir nota"); o loading desenha o resto. Trocar o rótulo por "Aguarde…" muda a largura do botão.
  • A espera longa diz o que está acontecendo com o objeto e o número: "Emitindo as notas do mês", "128 de 400 notas". Nunca "Processando…".
  • O cancelar nomeia o que para: "Cancelar importação", e diz o que fica feito ("As 128 notas já emitidas continuam valendo").

Acessibilidade

  • O loading do Button põe aria-busy e mantém o foco no botão; ele não some nem troca de lugar.
  • O Progress com label anuncia o nome e o valor; aria-valuetext diz o número na forma da tela ("128 de 400 notas").
  • A barra fina do isFetching sai com nome (labels.refreshing no DataTable), e a área revalidando leva aria-busy.
  • Quem pediu para reduzir movimento vê o esqueleto parado: as peças já leem a preferência.

No celular e no nativo

O Skeleton, o QueryBoundary, o Progress e o loading do Button existem no @rivocode/ui-native com os mesmos nomes. O DataList do nativo porta o isFetching e o isRefetchError com os nomes do web: as linhas ficam, e a barra fina corre no topo. No celular a espera longa ganha mais um motivo para sair da tela: a pessoa troca de app no meio, e o aviso com o resultado é o que ela encontra na volta.

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.