Construir formulários e estados de interação

Sem conferência no servidor, um cadastro aceita um telefone de dois dígitos, e a campanha de e-mail dispara meses depois para um endereço que nunca existiu. Validar um formulário é conferir cada campo antes de o dado entrar, e o formulário bem feito aplica a mesma regra nos dois lados.

Ele também desenha a tela do dado em quatro estados: vazio, carregando, erro e cheio. Quem aprova o cadastro perde venda por campo mal pensado, e regra escrita em dois lugares um dia discorda: o dado passa numa porta e falha na outra.

Por isso a descrição dos campos mora num arquivo só, importada pelas duas pontas, com os quatro estados provados num laboratório sem JavaScript.

O schema, a ficha que descreve tamanho, formato e obrigatoriedade de cada campo, como a especificação de uma peça, vive num arquivo só e alimenta as duas barreiras. A primeira fica no navegador, o programa em que a pessoa preenche. A segunda fica no servidor, o computador da empresa que recebe o pedido e grava no banco.

Quando a conferência só roda no navegador, qualquer pedido enviado por fora da tela entra sem crítica, e é assim que um endereço inexistente chega ao banco. A barreira do navegador existe para conforto: avisa antes de a pessoa perder o trabalho de preencher tudo, e isso aparece na taxa de conclusão.

A do servidor existe para controle, porque roda onde quem preenche não alcança. Se você só puder escrever uma das duas, escreva a do servidor.

Há ainda a norma internacional de acessibilidade da web, o WCAG 2.2, que manda no acesso ao formulário. O critério 3.3.8 diz que teste de memória não pode ser a única forma de provar quem você é. Na prática, isso obriga a aceitar senha colada.

Campo de senha que bloqueia colar reprova nesse critério, porque empurra quem usa um cofre de senhas para uma senha fraca digitada à mão. Quem perde é o cliente que desiste do cadastro na terceira tentativa.

Essa ficha é escrita com a ajuda de um validador, a biblioteca que transforma a regra em código que roda nas duas pontas. Em 2026 são três nomes, e a diferença entre eles é pequena para quem está começando.

Escolha o Zod por padrão, porque o ecossistema inteiro já o entende e o agente devolve código com ele sem você pedir. Troque para o Valibot, que pesa 1,37 kB, quando o formulário abrir em rede lenta e cada kB pesar. Deixe o ArkType para quando a validação já estiver medida como gargalo.

A biblioteca de formulário guarda o que a pessoa digitou e conversa com a ficha de campos. Na maioria dos projetos React ela é o react-hook-form. Ela deixa o navegador guardar o valor digitado e só confere na hora de enviar, por isso a tela não pisca a cada tecla.

Junto dela vêm dois ganchos do React que sabem se o envio está rodando, e eles mostram o botão ocupado sem código extra. Botão que não avisa nada é o que faz a pessoa clicar três vezes e gerar três cadastros.

Formulário com etapas e campos que dependem uns dos outros pede o TanStack Form, e projetos em Angular resolvem o mesmo com os Signal Forms.

Parte do aviso visual dispensa JavaScript e vem pronta no navegador. O seletor :user-invalid pinta o campo errado só depois de a pessoa mexer nele, e o :user-valid pinta o certo. Formulário que abre com tudo em vermelho antes da primeira letra foi escrito com o seletor antigo, :invalid puro, e já nasce reclamando.

A propriedade field-sizing faz a caixa de texto crescer conforme a pessoa escreve, sem barra de rolagem nem script. A accent-color pinta caixa de marcação e botão de opção com a cor da marca numa linha, sem redesenhar o controle nem perder teclado e leitor de tela.

As três peças vêm do próprio navegador, por isso não pesam no carregamento e continuam funcionando quando o script falha.

O dado que a pessoa entregou volta para a tela dela em outra hora, quase sempre trazido por outro sistema. Buscar esse dado é pedi-lo ao servidor e esperar a resposta, e toda tela que faz isso tem quatro estados: vazio, carregando, erro e cheio.

Sozinho, o agente entrega um rascunho que desenha só o cheio, porque é o que aparece quando você testa com a própria conta, já cadastrada. O cliente novo abre a mesma tela vazia e não sabe o que fazer ali.

Busque no servidor por padrão, porque a página chega com o texto pronto para buscador e assistente, e a chave secreta fica fora do navegador. Suba a busca para o navegador só quando o dado mudar com o clique, como o carrinho.

No navegador, o TanStack Query e o SWR guardam o cache, a cópia local de um dado já buscado. Eles mostram essa cópia na hora e conferem o dado novo por trás, então a tela não fica em branco esperando.

Histórico consultado sempre, como as vendas do mês, cabe no IndexedDB, o banco de dados que mora dentro do navegador. A regra é a mesma: mostrar o antigo e conferir depois. O estado carregando mostra um esqueleto com a forma do conteúdo, em vez de uma roda girando sem fim.

O estado de erro mostra mensagem específica e um botão de tentar de novo, porque sem esse texto a tela só gira e a pessoa fecha a aba. O estado vazio explica o que fazer e oferece o primeiro passo.

Antes de aprovar o cadastro, peça a quem construiu para repetir o envio por fora da tela, com um telefone de dois dígitos. Se o servidor aceitar esse pedido, só existe a barreira do navegador e o cadastro está aberto.

Depois confira os quatro estados numa tela que busca dado e tente colar a senha no campo de acesso. Deu certo quando o servidor recusa o telefone curto, a tela mostra erro com botão de tentar de novo e a senha cola.

Pedir formulário, upload, lista arrastável e editor de texto ao agente

Com a regra de campo escrita uma vez e os quatro estados desenhados, o pedido ao agente pode nomear formulário, upload, lista arrastável e editor.

Pedido sem nome de biblioteca volta com uma opção que ninguém no time conhece, e pedido sem os quatro estados volta só com o caminho de sucesso. Por isso quem pede formulário, upload, lista arrastável ou editor de texto escreve o nome da peça e prova os quatro estados antes de aprovar.

Biblioteca aqui é uma peça de software pronta, escrita e mantida por outra pessoa, que você encaixa no site em vez de construir do zero. Cada uma resolve um problema, e trocar depois de publicado custa caro, por isso a escolha acontece antes do primeiro pedido ao agente.

Você constrói e testa tudo isso antes de a API existir. API é a interface por onde um sistema entrega dado a outro, e aqui é o servidor que guarda os cadastros.

Um interceptador de rede, o MSW, responde no lugar do servidor verdadeiro enquanto o site está em desenvolvimento e nos testes, e fica de fora do site publicado. Com ele você força dez segundos de atraso e confere se a tela avisa em vez de girar sem fim.

Depois force um erro do servidor e, por fim, uma lista vazia. Os três caminhos aparecem numa tarde de teste, antes de qualquer chamado de suporte, e nenhum deles mostra tela branca.

O dado de exemplo leva nome brasileiro longo, como Maria Aparecida Gonçalves da Silva. É o texto longo que revela o cartão que estoura e o botão que quebra em duas linhas. Test User, com nove letras, esconde os dois defeitos.

Lista que a pessoa reordena com o dedo pede o dnd-kit, que pesa seis kB e funciona pelo teclado, e merece atenção acima de mil itens. Quadro do tamanho do Trello, com colunas, pede o Pragmatic drag-and-drop.

Upload de arquivo grande pede o Uppy. O envio é resumível, quer dizer que retoma de onde parou quando a conexão cai. Sem isso, um extrato de 40 MB volta ao começo a cada queda da rede. Para a foto do perfil, o campo de arquivo do próprio navegador resolve.

Paleta de comandos, aviso passageiro e gaveta do rodapé são cmdk, Sonner e Vaul, o trio padrão das telas montadas com shadcn. Tour de primeiro acesso é o driver.js, leve e suficiente. O auto-animate anima a lista que muda, com uma linha de código.

A paleta abaixo usa o cmdk de verdade, com quarenta destinos de um painel fictício. Abra pelo botão ou por Ctrl K, digite fat e veja o filtro achar Faturamento do mês e Fatura em atraso pela palavra parcial. Depois solte o mouse: setas, Enter e Esc resolvem tudo, e o foco volta ao botão quando a paleta fecha.

O que decide é o painel embaixo da paleta. O cmdk entrega filtro, teclado e leitura por leitor de tela; o visual fica com o seu CSS. Com mais de uma dúzia de destinos, esse trabalho compensa. Com cinco ou seis, um menu comum ou o dialog nativo do navegador resolve, e você desce um degrau na tabela.

Editor de texto é a decisão mais cara da lista, porque trocar de editor depois de publicado significa reescrever o conteúdo já salvo. O TipTap é o padrão para site de conteúdo e para texto escrito a várias mãos. Ele vem sem visual pronto, então alguém do time desenha a barra de botões.

Quando duas pessoas editam o mesmo documento ao mesmo tempo, quem junta as duas versões é o Yjs, e o TipTap é o que melhor se encaixa nele. O Lexical serve rede social e aplicativo de celular, onde o desempenho com muito texto pesa mais.

Bloco no estilo Notion é o Plate ou o BlockNote, que já traz o arrastar de blocos pronto. Para escrever código na tela, o CodeMirror parte de 50 kB e o Monaco pesa de dois a cinco MB. O Monaco só se justifica para quem passa a tarde programando.

As palavras da tela são parte do desenho. A skill frontend-design, o arquivo de instruções que o agente lê antes de desenhar, resume a regra em quatro pontos. Eles valem também para quem escreve o texto da tela à mão.

Nomeie pelo que a pessoa entende: ela gerencia avisos em vez de configurar um webhook, o aviso automático que um sistema manda a outro. O botão diz o que acontece, Salvar alterações, e nunca Enviar. A ação mantém o nome no fluxo inteiro, e Publicar gera um aviso que diz Publicado.

O erro explica o que houve e como resolver, sem pedir desculpa e sem vagueza. A tela vazia convida a agir, com o primeiro passo escrito. Tudo em tom conversado, verbo simples e sentence case, só a primeira letra maiúscula. Quem lê está no meio de outra coisa e não volta para decifrar rótulo.

Antes de aprovar a tela, peça o interceptador ligado só em desenvolvimento e nos testes, e force os três caminhos de falha. Releia cada botão e cada mensagem de erro pela régua da escrita.

Deu certo quando a demora mostra esqueleto, o erro mostra o que fazer, a lista vazia oferece o primeiro passo e nenhum botão diz apenas Enviar. Nomeie a biblioteca dentro do pedido, porque o nome é o que impede o agente de escolher por você.

Guia prático: página de captura com formulário e evento de medição

Formulário que valida e não mede deixa a campanha sem resposta: o anúncio gasta, o contato chega e ninguém sabe de qual peça ele veio. O roteiro abaixo junta a regra de campo deste capítulo com o evento generate_lead do Google Analytics 4, o nome recomendado pelo Google para o envio de um formulário ou de um pedido de informação.

No Next.js, a documentação da versão 16.3.8 indica o pacote @next/third-parties: o componente GoogleAnalytics entra no layout raiz com o ID de medição, carrega depois da hidratação e a função sendGAEvent envia o evento. O pacote segue marcado como experimental. Quem já usa o Google Tag Manager configura o Analytics por ele, em vez de somar os dois.

O evento abre uma família. qualify_lead, working_lead e close_convert_lead registram o que acontece com o contato depois, e alimentam o relatório de aquisição de leads.

Guia prático: escolher o canal de captura pelo setor

A dúvida de todo projeto de captação é se o botão abre um formulário, uma conversa ou uma agenda. Os templates medidos em 07/10/2026 mostram que o setor já responde boa parte. Dos 10 templates com WhatsApp, 8 são os de negócio local em português; nos 5 de advocacia, 4 usam WhatsApp com mensagem pré-escrita, diferente para cada serviço, e só o mais institucional usa "Agende uma consulta". Nenhum dos 12 templates premium em português tem um elemento form. Já os de SaaS, em inglês, chamam para teste grátis ou demonstração.

A biblioteca de 1.451 componentes mostra o outro lado. Há 126 componentes de formulário, mas só 19 deles funcionam sem pacote extra; pedir "um formulário bonito" costuma trazer biblioteca de animação para três campos. Formulário é conteúdo, não efeito: o que decide o resultado são as perguntas, os rótulos e a mensagem de erro, não a borda que brilha.

Aplicar os recursos ao projeto