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.
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".
- 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.
- A pessoa precisa sair para buscar um dado no meio? O código do serviço na prefeitura, o comprovante no e-mail.
- Uma etapa tem custo próprio ao ser confirmada? Consultar o CNPJ na Receita, reservar o horário, gerar o QR.
- 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
Fieldsete título. Campo que poucos usam vai para umCollapsible("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 oSteps. - Passo que só se chama "Passo 2" não era um passo, era uma rolagem.
As peças
Steps: a régua, comonStepChangepara 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.useZodFormcom os campos de todas as etapas.Result: o desfecho, no lugar do formulário.
Comportamento
- Um formulário só por baixo dos passos. Um
useZodFormcom 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([...]))douseWizardcobra 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
StepspeloonStepChange. 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
localStoragefica 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), comuseLocalStorage, 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
loadingenquanto envia. Depois dele, o desfecho é oResult. - 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
Checkboxmarcado "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
Stepsmarca o passo atual comaria-current="step". ComonStepChange, os já feitos são botões de verdade; o atual, os futuros e os feitos semonStepChangenão são botão nenhum, nem desabilitado: não param noTab. - 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 cadatrigger()que falhou emvalidationCount, 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 porlabels.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.