Pular para o conteúdo

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

Uma tela ou várias: o wizard

As quatro perguntas antes de quebrar em passos, e o wizard que não perde nada ao voltar.

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

Wizard não é o padrão. O padrão é um formulário só, em seções; passos só quando uma etapa depende da anterior.

O problema

Quebrar quinze campos em três telas de cinco não diminui o trabalho, só esconde o tamanho dele e tira a visão do conjunto. E o wizard mal feito cobra de novo: perde o que foi digitado ao voltar, pede duas vezes o mesmo dado e confirma em cima da revisão.

Quando usar

A pergunta não é quantos campos existem, é quantas decisões independentes a pessoa toma.

Forma Quando Peça
Um formulário só os campos se respondem juntos, e a pessoa já sabe tudo Card com Field
Passos há decisão que muda os campos seguintes, ou a pessoa precisa buscar dado no meio Steps + WizardFooter
Folha lateral a tarefa é acessória e o contexto de trás importa Sheet
Diálogo uma decisão, curta, que não pode ser dispensada por engano Dialog

Responda as quatro perguntas antes de quebrar em passos; wizard só se pelo menos uma for "sim".

  1. Uma resposta muda o que se pergunta depois? Pessoa física ou jurídica troca os campos; o tipo de serviço decide as alíquotas.
  2. A pessoa precisa sair para buscar um dado no meio? O código do serviço na prefeitura, o comprovante no e-mail.
  3. Uma etapa tem custo próprio ao ser confirmada? Consultar o CNPJ na Receita, reservar o horário, gerar o QR.
  4. A tarefa é longa e rara, e a pessoa se perde sem mapa? Abrir a empresa no sistema pela primeira vez, configurar a emissão.

Quando não usar

  • Tudo "não" é formulário único, mesmo com trinta campos, em seções com Fieldset e título. Campo que poucos usam vai para um Collapsible ("Mais opções"), e não para um passo a mais.
  • Perguntas uma por vez, com ramificação pela resposta (triagem, pesquisa, o agente pedindo esclarecimento) é o Questionnaire, e não o Steps.
  • Passo que só se chama "Passo 2" não era um passo, era uma rolagem.

As peças

  • Steps: a régua, com onStepChange para voltar a um passo já feito.
  • WizardFooter: Voltar e o avanço, sempre no mesmo lugar.
  • useWizard: o passo da vez, next, back, goTo, isFirst, isLast.
  • useZodForm com os campos de todas as etapas.
  • Result: o desfecho, no lugar do formulário.

Comportamento

  • Um formulário só por baixo dos passos. Um useZodForm com os campos de todas as etapas, e cada passo mostra a parte dele. Formulário por passo perde o que foi digitado ao voltar.
  • Valida o passo antes de avançar, e só ele. next(() => form.trigger([...])) do useWizard cobra os campos daquele passo; o "Próximo" fica travado enquanto a checagem assíncrona roda, e dois toques andam um passo só.
  • Voltar nunca perde nada, e os passos já feitos são clicáveis no Steps pelo onStepChange. Pular para a frente não: o passo seguinte depende do anterior.
  • Voltar um passo e errar o envio nunca perdem nada: o formulário fica na memória enquanto a tela está aberta.
  • Rascunho entre visitas é decisão do projeto, e não da biblioteca. Guardar no navegador para sobreviver a recarregar a página expõe o que foi digitado: o localStorage fica na máquina, sem criptografia, e qualquer script da página o lê. Se o produto quiser, guarde só o que não for sensível (nunca senha, cartão, documento, dado de saúde ou financeiro), com useLocalStorage, e limpe no sucesso do envio. Na dúvida, não guarde.
  • A última etapa é revisão, com cada parte resumida e um "Alterar" que volta ao passo dela. O botão final diz o efeito e leva loading enquanto envia. Depois dele, o desfecho é o Result.
  • Sem confirmação em cima da revisão. A revisão já é a confirmação.
  • Não peça duas vezes o que a pessoa já disse. O e-mail do passo Cliente volta preenchido no passo Envio, e o endereço de cobrança nasce igual ao de entrega, com um Checkbox marcado "O endereço de cobrança é o mesmo da entrega" que, desmarcado, abre os campos. É a WCAG 3.3.7, nível A: digitar de novo só para senha nova e para dado que deixou de valer.
const STEPS = [
  { id: 'cliente', title: 'Cliente' },
  { id: 'servico', title: 'Serviço' },
  { id: 'revisao', title: 'Revisão' },
]
const FIELDS = [['document', 'name'], ['service', 'amount'], []] as const

const form = useZodForm(schema, { defaultValues: EMPTY })
const wizard = useWizard(STEPS)
const [validationCount, setValidationCount] = useState(0)

async function checkStep() {
  const ok = await form.trigger([...FIELDS[wizard.step]])
  if (!ok) setValidationCount((n) => n + 1)
  return ok
}

<Steps steps={STEPS} step={wizard.step} onStepChange={wizard.goTo} />
<FormErrorSummary validationCount={validationCount} />
<WizardFooter>
  {!wizard.isFirst && <Button variant="secondary" onClick={wizard.back}>Voltar</Button>}
  {wizard.isLast ? (
    <Button key="submit" type="submit" loading={form.formState.isSubmitting}>Emitir nota</Button>
  ) : (
    <Button key="next" type="button" onClick={() => wizard.next(checkStep)}>
      Continuar
    </Button>
  )}
</WizardFooter>

O key diferente nos dois botões faz o React criar outro botão no último passo, em vez de trocar o tipo do mesmo. O useWizard já troca o passo só depois que o clique termina; a chave é a segunda trava, para assistente escrito sem ele.

O formulário é um só para os três passos, então voltar da Revisão ao Cliente encontra tudo como estava.

Texto

  • Cada passo é nomeável por substantivo: "Cliente", "Serviço", "Revisão".
  • O botão final diz o efeito: "Emitir nota", e não "Concluir".
  • O avanço dos passos do meio é "Continuar"; o recuo é "Voltar", e nunca "Cancelar", que soa como desistir de tudo.

Acessibilidade

  • O Steps marca o passo atual com aria-current="step". Com onStepChange, os já feitos são botões de verdade; o atual, os futuros e os feitos sem onStepChange não são botão nenhum, nem desabilitado: não param no Tab.
  • Ao trocar de passo, leve o foco ao título do passo novo, senão o leitor de tela continua lendo o rodapé.
  • O erro de validação do passo aparece no campo, e o resumo dos erros no topo do passo quando houver mais de um (FormErrorSummary). O resumo espera um envio, e o passo não envia: conte cada trigger() que falhou em validationCount, e cada número novo mostra os erros e leva o foco ao resumo (no nativo, anuncia). O título padrão diz "para enviar"; no passo do meio, troque por labels.title ("Corrija 2 campos para continuar").

No celular e no nativo

No celular o Steps vira "2 de 4" com o nome do passo, e o WizardFooter gruda embaixo (sticky), com Voltar e o avanço sempre no mesmo lugar. O fundo dele é o de quem está em volta: dentro do Card, do Dialog ou da Sheet ele pinta a superfície deles sozinho, e solto na página pinta o fundo da página. Cartão montado à mão não diz o fundo, e o rodapé sai no da página: use o Card. Na mesa o avanço fica sempre à direita, mesmo no primeiro passo, sem o Voltar. No @rivocode/ui-native o Steps é só esse modo estreito, sem onStepChange, e o useWizard() atravessa inteiro.

Os blocos que o aplicam

Nenhum bloco do site é um wizard ainda. O Cadastro de paciente, em https://ds.rivocode.com.br/blocos, é o formulário único em seções: a resposta quando a checagem dá "não" nas quatro perguntas.

@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.