01Arquivo

padroes-frontend.md

Padrões de frontend

Formulários, textos de interface, listas, estados, URL, acessibilidade e layout, com os princípios por trás de cada regra.

Voltar para skills

Padrões de frontend

Como construir interfaces. Vale para todo projeto novo; cada projeto guarda a versão aplicada no próprio docs/design.md e registra lá as decisões que são só dele.

Stack mais comum: Next.js (App Router), TypeScript, Tailwind CSS v4, Untitled UI (só o gratuito, componentes react-aria) e zod + react-hook-form; o backend muda de projeto para projeto. Os princípios valem em outra stack; os nomes de componentes e props são dessa. Os exemplos de formulário e formatação vêm de aplicações brasileiras (CPF, CNPJ, CEP, pt-BR): troque pelos equivalentes do idioma e do país da sua aplicação.

Princípios

  • Mínimo de preenchimento. Todo campo já vem com o padrão mais provável (responsável = quem está logado, prioridade baixa, prazo em 7 dias, o contexto mais provável). A pessoa só ajusta o que for diferente.
  • Ação crítica nunca vem pré-escolhida. Excluir, pagar, assinar e enviar para o cliente exigem confirmação explícita, sem opção marcada que leve ao erro.
  • A interface não é a barreira de segurança. Esconder botão e item de menu é só experiência de uso. Quem decide é o servidor e, no banco, a RLS.
  • Tela nova entrega junto a rota, o item de navegação com a permissão mínima e os estados de carregando, erro e vazio. Nada de item de menu sem rota.
  • Procurar antes de criar. Antes de um botão, input, modal, tabela, paginação, date picker, upload ou estado vazio, procurar em src/components/ e depois no Untitled UI. O que faltar é montado com os componentes gratuitos, na linguagem visual do Untitled.
  • Conferir a assinatura real do componente. Os componentes são react-aria: isDisabled, isLoading, isInvalid, onPress, não disabled, loading ou onClick.
  • Decisão de interface vai para o docs/design.md na mesma alteração do código.

Idioma e texto

  • Código, rotas internas, banco e comentários em inglês. O que a pessoa lê (interface, erros, validação, e-mails) no idioma da aplicação, inclusive os textos que vêm em inglês nos componentes do Untitled.
  • Parâmetros de URL que aparecem para a pessoa ficam no idioma da aplicação (ex.: ?busca, ?tipo, ?ver).
  • Tratamento por "você", informal e respeitoso.
  • Maiúscula só no início da frase e em nomes próprios, também em títulos e botões.
  • Botão diz o que faz: verbo + objeto ("Criar clínica", "Salvar alterações", "Desativar clínica"). Nada de "OK", "Enviar" ou "Confirmar" soltos.
  • Título de confirmação em pergunta: "Desativar Clínica Aurora?". A descrição diz o que acontece e se dá para desfazer.
  • Gênero e número acompanham a entidade ("O consultório fica marcado como inativo", "A clínica volta para a rede"; "1 clínica", "3 clínicas"). Quando o texto muda por tipo, ele fica num mapa por tipo (COPY[kind]), não em condicionais espalhadas.
  • Gênero da marca definido no início do projeto e usado sempre igual (ex.: "a Acme").
  • Erro nunca culpa a pessoa: "Não foi possível salvar agora. Tente novamente em instantes."
  • Validação no imperativo, curta: "Informe o nome.", "Use pelo menos 8 caracteres.", "Confira o CNPJ."
  • Texto de apoio no campo quando a consequência não é óbvia: "Mudar o endereço quebra os links já divulgados."
  • Campo opcional não leva "opcional" no placeholder, no apoio nem na descrição: o * marca os obrigatórios, e a ausência dele já diz o resto. O placeholder mostra um exemplo do formato ("00.000.000/0000-00", "nome@email.com") ou fica vazio; o apoio explica quando preencher.
  • Antes de publicar texto de marketing ou longo, passar pelo humanizer.

Formulários

  • Validação no cliente para resposta rápida e de novo no servidor, que decide. O schema zod fica em features/<área>/schema.ts, sem dependência de servidor, e é o mesmo nos dois lados (zodResolver no cliente, safeParse na server action).

  • react-hook-form com Controller em volta dos inputs do Untitled. O erro vai no hint do campo, com isInvalid. O <form> usa noValidate (a validação é a nossa, não a do navegador).

  • Uma forma só de resposta para toda action:

    type ActionResult<Field extends string = string> =
        | { ok: true }
        | { ok: false; error?: string; fieldErrors?: Partial<Record<Field, string>>; saved?: boolean };
    
    • fieldErrors volta para os campos com setError; error aparece no rodapé do formulário.
    • saved: true quando o registro foi salvo e só um passo secundário falhou (ex.: a foto). O formulário avisa o que repetir, sem perder o que foi salvo.
    • Erros do banco viram mensagem num lugar só (toActionError): registro repetido → "Já existe um cadastro com esses dados."; permissão negada pela RLS → "Sua conta não tem permissão para esta ação."; o resto → mensagem genérica, e o erro real vai para o log do servidor.
    • Conflito de unicidade (endereço, CNPJ, e-mail) volta como erro no próprio campo.
  • Arquivo vai junto com os dados num FormData só: o JSON em values e o arquivo em outro campo (ex.: avatar, removeAvatar).

  • Formulário longo em etapas numeradas, no mesmo modal (ModalSteps/ModalStep): seções "01", "02"... empilhadas numa rolagem só, com o número em fonte mono na cor da marca, o título e uma descrição curta. Não é um passo a passo: um botão só salva tudo, de qualquer ponto. Os obrigatórios ficam na primeira etapa, e o erro de validação leva o foco ao primeiro campo inválido. O número sai de um contador de CSS, então etapa condicional renumera sozinha.

  • Um layout para todo modal de formulário, no modelo do "User settings" do Untitled: ícone em destaque ao lado do título, divisória abaixo do cabeçalho e acima do rodapé, só o conteúdo rolando entre eles, e "Cancelar" e a ação principal no tamanho normal, à direita (empilhados no celular). Cada campo numa linha, com o rótulo à esquerda (acima, no celular) e o campo à direita; dois campos curtos podem dividir a linha. As linhas se separam por uma divisória tracejada, e as etapas, por uma contínua. O rótulo é visual, e cada campo leva o seu aria-label. Em linha de toggle, checkbox ou rádio, o rótulo alinha com o texto do controle, não com o meio de um input. Nada no modal rola na horizontal: textos de apoio quebram a linha. As telas de configurações seguem o mesmo desenho.

  • Criar e editar usam o mesmo modal. Mudam o título, a descrição e o texto do botão. A edição monta os valores a partir da linha (toValues(row)) sobre as constantes EMPTY_*.

  • O modal reabre limpo trocando a key a cada abertura, sem lógica de reset.

  • Enquanto salva: o botão principal com isLoading e showTextWhileLoading; cancelar, fechar e os outros controles com isDisabled; o modal não fecha (isDismissable={!isSubmitting}).

  • Regras comuns de campo: nome com 2 a 120 caracteres; e-mail com trim().toLowerCase(); campo opcional aceita ""; confirmação (ex.: digitar o nome para excluir) com refine e path apontando para o campo certo. Sem campo de senha: a entrada é pelo código por e-mail.

  • Máscara enquanto digita: CNPJ, CPF, telefone, CEP e data são formatados durante o preenchimento, com teclado numérico. O separador só aparece antes do próximo dígito, para apagar sem travar; o telefone vira celular no 11º dígito; colar com ou sem pontuação dá no mesmo.

  • Valores em dinheiro: o símbolo da moeda fica num addon colado ao começo do campo, e o valor enche da direita, como a maquininha ("15000" vira "150,00"; apagar tira o último dígito). Guardado em centavos, como inteiro, para as somas nunca arredondarem errado.

  • Documentos e telefones: validados pelos dígitos (verificadores, no caso de CNPJ e CPF), guardados só com números e exibidos formatados nas listas.

  • Data sem hora (ex.: nascimento): digitada como "dd/mm/aaaa", em vez de date picker, que obriga a navegar por décadas.

  • Data próxima (consulta, agendamento, prazo): o mesmo campo digitado, com um botão de calendário dentro dele, que abre no mês da data, com hoje destacado e um atalho "Hoje"; escolher o dia preenche e fecha. Digitar continua valendo.

  • Endereço postal: o CEP preenche rua, bairro, cidade e UF por um serviço público (ex.: ViaCEP), como sugestão editável, e o foco vai para o número. CEP não encontrado avisa no campo e deixa digitar. Endereço opcional é tudo ou nada, na validação e no banco.

  • CNPJ preenche a empresa: com o CNPJ completo e válido, a razão social vem de um serviço público (ex.: BrasilAPI) como sugestão editável; situação diferente de "Ativa" aparece no apoio do campo.

  • WhatsApp: toggle "O WhatsApp é o mesmo número", ligado por padrão; desligado, abre o campo.

  • Endereço (slug) sugerido a partir do nome, sem acentos, até a pessoa editar o campo; depois disso, o nome não mexe mais nele. Lista de nomes reservados no código.

  • Campo só de leitura quando a troca tem efeito fora da tela (ex.: o e-mail que é o login), com o texto dizendo como trocar.

Ações críticas

  • Desativar, excluir, pagar, assinar e enviar para cliente passam por um modal de confirmação próprio (ConfirmModal, role="alertdialog"), com o botão de confirmar sem foco inicial e o texto dizendo o que acontece.
  • Dentro de um modal, remover um item de uma lista (um pagamento, um anexo) confirma na própria linha, sem abrir outro modal por cima: "Remover" troca a linha pela pergunta ("Remover o pagamento de R$ 100,00?"), com "Voltar" e a ação destrutiva escrita por extenso.
  • Ação que se chama "Cancelar ..." (cancelar consulta, cancelar assinatura) não convive com outro "Cancelar" no mesmo modal: o botão de sair vira "Fechar" no formulário e "Voltar" na confirmação.
  • Excluir sem "desfazer" na tela pede para digitar o nome do registro. A comparação ignora maiúsculas e espaços extras.
  • Excluir é lógico (deleted_at): o registro some das telas, libera os campos únicos (índices parciais) e volta por uma aba "Excluídos", que só aparece depois da primeira exclusão.
  • Restaurar não é destrutivo: abre um modal com os campos únicos já preenchidos, para trocar se outro registro tiver ocupado.
  • Excluir definitivamente (tirar do banco, sem volta) é um segundo passo, só na aba "Excluídos": ao lado de "Restaurar", um botão só com a lixeira, vermelho e sem fundo, com aria-label. Onde não há exclusão lógica, fica no menu de ações. Sempre com o nome digitado, e a descrição diz o que sai junto e o que continua.
  • Desativar deixa o registro na lista, marcado como inativo. Reativar também pede confirmação.
  • Ninguém faz em si mesmo a ação que corta o próprio acesso (o item fica desabilitado).

Feedback

  • Sucesso em toast: cartão no canto inferior direito, com ícone verde, a mensagem do que foi salvo e "Fechar", role="status", some em poucos segundos.
  • Salvo com pendência em toast de aviso: ícone âmbar, o que foi salvo e o que falta fazer ("Horário bloqueado. 2 consultas continuam marcadas nesse período: remarque ou cancele na Agenda."), e fica mais tempo, porque pede uma ação.
  • Erro fica no formulário: <p role="alert"> em vermelho, no rodapé, à esquerda dos botões (com a ação secundária, quando houver; no celular, acima dos botões), para o rodapé não crescer.
  • Salvar nunca é mudo: com a validação falhando, o rodapé diz "Confira os campos destacados." e o modal rola até o primeiro campo inválido e põe o foco nele, mesmo quando o campo é um select (cujo ref pode não receber foco) ou está fora da área visível.
  • Sem alteração, sem botão: em formulário de edição, "Cancelar" e "Salvar" ficam desabilitados até algo mudar; preenchimento automático conta como alteração.
  • Mensagem de entrada não revela se a conta existe: o login pede o e-mail e mostra "Confira seu e-mail" (o passo do código) com ou sem conta; quem não tem conta só não recebe nada.
  • Link expirado ou já usado troca o botão por "Pedir um link novo".
  • Excesso de tentativas: "Muitas tentativas. Aguarde alguns minutos e tente de novo."

Estados de tela

  • Toda rota tem loading.tsx e error.tsx próprios, dentro do layout da área.
  • Carregando: skeleton no formato da tela (lista, configurações, calendário, detalhe ou painel), com blocos que pulsam e param com prefers-reduced-motion, para a página não pular quando chega. O texto "Carregando ..." fica para o leitor de tela, num role="status".
  • Dados que só um modal usa não seguram a página: vêm em segundo plano depois que ela aparece, e abrir o modal antes disso espera por eles.
  • Erro: ícone de alerta em vermelho, "Não foi possível carregar ", "Tente de novo em instantes. Se continuar, avise o suporte técnico." e o botão "Tentar novamente".
  • Página inexistente: "Erro 404", "Página não encontrada" e "Voltar ao início". Erro geral: "Algo deu errado".
  • Lista vazia: ícone na cor da marca, explicação curta e o botão de criar. O botão do cabeçalho some enquanto a lista está vazia, para não duplicar a ação.
  • Busca sem resultado tem texto próprio ("Ninguém encontrado com "x"") e não mostra o botão de criar.
  • Sem acesso: ícone cinza, explicação e só a saída possível (ex.: "Sair").

Listas e tabelas

  • Cartão de tabela (TableCard) com título e contador; cada linha com menu de ações (três pontos, aria-label="Ações de <nome>").
  • Clicar na linha abre o registro (a edição), sempre que a tabela tiver essa ação: é o caminho mais curto, sem passar pelo menu. A linha ganha o cursor de clique, e Enter faz o mesmo pelo teclado. O menu de três pontos continua, com "Editar" e as outras ações (desativar, excluir), que nunca disparam pelo clique na linha.
  • Sem rolagem horizontal, salvo exceção rara e justificada. Para caber:
    • dado secundário vira subtítulo da coluna principal (endereço, CNPJ, e-mail);
    • colunas secundárias somem nas larguras menores (max-md:hidden, max-lg:hidden, max-xl:hidden, no cabeçalho e na célula). Nome e ações ficam sempre;
    • o que não ajuda a decidir nada na lista (ex.: data de criação) sai.
  • Nome com avatar ao lado (AvatarLabelGroup); entidade sem foto mostra as iniciais; pessoa sem foto mostra o ícone de perfil.
  • Status com BadgeWithDot: verde ativo, cinza inativo, vermelho bloqueado.
  • Paginação pela URL, 20 por página; página além do fim volta para a última. No celular, os textos da paginação ficam só para leitor de tela.
  • Abas de filtro pela URL, com o número de cada uma.

Estado na URL

  • Filtro, aba, busca e página ficam na URL, para o link poder ser compartilhado e o "voltar" funcionar.
  • Trocar um parâmetro mantém os outros; a página 1 sai da URL; trocar filtro ou busca volta para a página 1.
  • A busca atualiza a lista 300 ms depois de a pessoa parar de digitar, com router.replace(..., { scroll: false }).
  • Todo valor lido da URL é higienizado (parsePage, parseSearch com limite de 100 caracteres).

Navegação e permissões

  • Três camadas, cada uma com um papel: o proxy redireciona por sessão (só experiência); o layout do grupo de rotas confere o papel e redireciona; o banco (RLS) decide.
  • O menu é uma configuração por contexto (grupos mais itens de rodapé), não condicionais no JSX.
  • Grupos pelo trabalho que a pessoa faz, não pela tabela do banco: "Início" sozinho no topo, sem rótulo, e depois os grupos com rótulo. Nada de grupo com um item só.
  • Configurações da conta e da plataforma ficam no rodapé da sidebar, acima do cartão do usuário, separadas do trabalho do dia a dia. O que um cliente configura uma vez (perfil, horários, serviços) desce para um grupo "Configurações" perto do rodapé, com o progresso no rótulo ("3 de 5") e um ponto âmbar no item incompleto enquanto a configuração não termina.
  • O menu avisa as pendências: contador pequeno no fim do item (cor da marca; âmbar quando é urgente), com o que ele conta no title e para o leitor de tela. Status vira um ponto colorido com o nome escrito para o leitor de tela. Sem pendência, nada aparece.
  • A sidebar só navega: nada de botão de ação nela (ex.: "Nova consulta"); a ação fica no cabeçalho de cada tela.
  • Atalho para fora do painel (ex.: abrir a página pública) fica no hover do item relacionado, como link irmão, e não num item à parte.
  • Quem tem mais de um vínculo troca de contexto num seletor no cartão do usuário, no rodapé da sidebar; trocar de contexto sempre leva para o início da área.
  • Página de detalhe mantém ativo o item do menu de onde ela vem (a ficha de um cadastro acende o item da lista); o início só acende na própria página.
  • Uma área logada só, com sidebar fixa no desktop e cabeçalho com menu no celular.
  • Sessão presa a um endereço só: www redireciona (308) para o domínio principal.

Layout

  • Página: mx-auto max-w-7xl px-4 py-8 lg:px-8, com gap-8 entre os blocos.
  • Cabeçalho da página (PageHeader): título, descrição e ações à direita.
  • Modal de formulário com max-w-140 (poucos campos) ou max-w-170 (muitos campos ou etapas); de confirmação com max-w-100. Rodapé com a ação secundária à esquerda (quando houver) e "Cancelar" + ação principal à direita; no celular, os botões empilham (flex-col-reverse) em largura total.
  • Tela de configurações no layout Settings 03 do Untitled (montado com os componentes gratuitos): título e descrição da seção sobre uma linha; uma linha por campo, com o rótulo e a explicação à esquerda (acima, no celular) e o campo à direita, separadas por divisórias; no fim, "Cancelar" (volta ao que foi salvo) e "Salvar". O rótulo da linha é visual, e cada campo leva o seu aria-label.
  • Painel de números no desenho dos dashboards 03 e 04 do Untitled (PRO, montado com os componentes gratuitos): o período num controle segmentado acima dos números, e não num select; cada número num cartão com uma moldura cinza e o título em cima, e um painel branco por dentro com o valor em destaque e a frase que explica; blocos de cartões com título e uma linha de contexto, e a ação do bloco à direita. A tabela abaixo leva os filtros (abas e select) numa faixa cinza entre o cabeçalho e as linhas, dentro do mesmo cartão. Registrado em 2026-11-13.
  • Campos empilhados, um por linha; campos curtos e opcionais podem dividir a linha a partir do sm.
  • Só tema claro, salvo decisão do projeto. A classe do tema fica fixa no <html>, sem biblioteca de tema.

Ícones e imagens

  • Só @untitledui/icons. size-4 ao lado de texto, size-5 em menus e botões de ícone.
  • Ícone decorativo com aria-hidden; botão só de ícone com aria-label.
  • Foto de entidade: PNG, JPG ou WEBP, até 2 MB, no Storage com caminho <tipo>/<id>/<nome-aleatório>. O banco guarda só o caminho; a URL sai de uma função.
  • Upload com a sessão do próprio usuário; as policies do Storage decidem quem grava onde.
  • Select, combobox e dropdown que listam pessoas ou cadastros mostram a foto em cada opção e, depois de escolhida, no próprio campo. Sem foto, o placeholder das listas (ícone de perfil para pessoa, iniciais para entidade). A pessoa reconhece pela foto antes de ler o nome, e homônimos se separam.
  • Marca de terceiro conhecida (convênio, banco, bandeira de cartão, app como WhatsApp ou Google) aparece com a logo ao lado do nome, para a pessoa reconhecer antes de ler. A logo não substitui o nome (imagem decorativa, alt=""), tem a mesma altura em toda a lista, fica no próprio sistema (versionada no projeto, SVG de preferência, ou enviada pelo admin quando a lista de marcas é um cadastro), nunca carregada do site da marca, sem alterar cores nem proporções, e o item sem logo mostra iniciais ou um ícone neutro no mesmo tamanho. O formato depende da interface: quadrada (o símbolo) onde o espaço é curto e os itens se repetem (checkbox, select, badge, tabela); retangular (o logotipo horizontal) onde a marca tem espaço e destaque (página pública, cartões). Guardar as duas versões quando existirem.

Formatação

  • Datas com Intl.DateTimeFormat no locale e no fuso da aplicação (ex.: "pt-BR", "America/Sao_Paulo", dateStyle: "medium"), num formatador só.
  • Comparação e busca sem diferenciar maiúsculas e acentos (toLocaleLowerCase(locale) + normalize("NFD")).
  • Iniciais: primeira letra das duas primeiras palavras.

Acessibilidade

  • Foco visível (outline-focus-ring focus-visible:outline-2); item ativo com aria-current e, na sidebar, destacado na cor da marca (fundo claro, texto e ícone da marca), não no cinza padrão.
  • Opção escolhida num grupo de botões (segmentado) com o mesmo destaque da marca, mais a borda: o cinza padrão do Untitled quase não se distingue das outras opções.
  • Grupo de abas com aria-label="Filtrar ...".
  • Coluna de ações com aria-label, mesmo sem texto visível.
  • Status lido por leitor de tela quando só a cor ou o ícone o mostram (sr-only).
  • Alt descritivo, no idioma da aplicação, nas imagens de conteúdo; vazio nas decorativas.
  • Respeitar prefers-reduced-motion em toda animação e transição de rolagem. Conteúdo legível sem JavaScript: animação de entrada só quando o script marcou a página.

Metadados

  • <html lang> no idioma da aplicação (ex.: pt-BR); título no formato "%s | <Marca>", com cada página definindo o seu.
  • Sites à parte (guia da marca, roadmap) com título próprio, favicon e fora dos buscadores (robots: noindex, nofollow).
  • Commit curto no canto das telas logadas e do login, para saber que versão está no ar, com link para o commit no repositório (abre em nova aba; repositório privado só abre para quem tem acesso).

Sites de apoio

Todo projeto com marca própria ganha, em subdomínio, fora dos buscadores:

  • Guia da marca (design.): conceito, voz (pilares com "Escrevemos" e "Evitamos"), logo, cores, tipografia e download dos arquivos. O produto não importa nada de lá.
  • Roadmap (roadmap.): gerado do docs/roadmap.md no build, com o progresso por fase e por etapa.

Documentação do projeto

Todo projeto tem em docs/, criados no início e mantidos em dia: roadmap.md, produto.md, design.md, concorrentes.md, migrations.md, deploys.md e gotchas.md. O README.md da raiz é a fonte de verdade de setup, comandos, variáveis e deploy.