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ãodisabled,loadingouonClick. - Decisão de interface vai para o
docs/design.mdna 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 (zodResolverno cliente,safeParsena server action).react-hook-form com
Controllerem volta dos inputs do Untitled. O erro vai nohintdo campo, comisInvalid. O<form>usanoValidate(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 };fieldErrorsvolta para os campos comsetError;erroraparece no rodapé do formulário.saved: truequando 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
FormDatasó: o JSON emvaluese 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 constantesEMPTY_*.O modal reabre limpo trocando a
keya cada abertura, sem lógica de reset.Enquanto salva: o botão principal com
isLoadingeshowTextWhileLoading; cancelar, fechar e os outros controles comisDisabled; 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) comrefineepathapontando 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.tsxeerror.tsxpró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,parseSearchcom 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
titlee 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ó:
wwwredireciona (308) para o domínio principal.
Layout
- Página:
mx-auto max-w-7xl px-4 py-8 lg:px-8, comgap-8entre 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) oumax-w-170(muitos campos ou etapas); de confirmação commax-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-4ao lado de texto,size-5em menus e botões de ícone. - Ícone decorativo com
aria-hidden; botão só de ícone comaria-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.DateTimeFormatno 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 comaria-currente, 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-motionem 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 dodocs/roadmap.mdno 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.