O que um frontend profissional deve ter e como estruturá-lo

Um frontend não é «a parte bonita»

Para o usuário de uma empresa, o frontend é o produto: é ali que se ganha ou se perde a cotação, o cadastro ou o pagamento. E, ainda assim, é uma das partes menos auditadas. Um sistema pode ter um backend impecável e um frontend que ninguém consegue manter, que não se lê bem no celular, que o Google não entende ou que quebra toda vez que a marca muda.

Esta é a lista do que, a nosso ver, um frontend profissional deve ter, e por quê. Não é uma receita: é o que convém exigir da equipe ou do fornecedor, e como reconhecer se o frontend tem isso.

1. Componentes com uma direção, não uma pasta de «coisas»

Uma interface profissional se constrói com peças pequenas e reutilizáveis. A própria documentação do React coloca assim: um componente deve, idealmente, cuidar de uma única coisa, e, se crescer, é dividido em subcomponentes.

Um vocabulário útil é o do Atomic Design (Brad Frost): átomos (botão, campo), moléculas (um campo com rótulo e mensagem de erro) e organismos (um cabeçalho, um formulário completo). Estendemos esse vocabulário com seções e páginas quando isso ajuda a governar o produto. É uma convenção, não uma lei. O que a torna valiosa é uma única regra: a dependência flui em uma só direção. Uma peça básica não conhece as peças de produto que a usam.

E uma disciplina que evita muito gasto: abstrair tarde. Um padrão vira componente compartilhado quando já se repetiu e as variantes se estabilizaram; abstrair antes costuma custar mais do que uma duplicação visível.

Hoje se sabe quais telas mudam se amanhã mudar a cor principal da marca?

2. Um sistema de design com tokens

Um token de design é, na definição do grupo que trabalha no formato dos tokens, uma informação com um nome legível: no mínimo, um par de nome e valor (por exemplo, a cor do texto principal). O princípio é simples: a cor, a tipografia e o espaçamento não são escritos no componente; vêm de um token. Mudar a marca passa a ser mudar um valor, não editar cada tela.

Uma ressalva honesta: o formato padrão de tokens do Design Tokens Community Group continua sendo um rascunho, e o próprio texto pede que ainda não seja implementado. Os tokens podem ser definidos hoje no sistema de design e exportados quando o padrão se estabilizar.

3. Storybook, e o que se entrega com ele

Um componente sem documentação é difícil de usar bem para quem não o escreveu. O Storybook permite construir e revisar cada componente de forma isolada, com as variantes e os casos de difícil alcance, e funciona como documentação gerada a partir das próprias histórias (a função de autodocumentação faz isso a partir dos metadados do componente), de modo que ela se mantém perto do código; vale, porém, o que valerem as histórias: devem refletir o uso real. Para uma empresa, o importante é o que ela recebe: um catálogo navegável que design, QA e negócio podem abrir, e não uma captura de tela em um chat.

Como organizá-lo para que seja um contrato —com hierarquia, estados e revisões— explicamos à parte: Como estruturar um Storybook que sirva de contrato. Aqui, apenas a exigência: um catálogo que depende de alguém se lembrar de publicá-lo fica desatualizado; publique-o automaticamente quando as mudanças forem aprovadas.

4. Testes em três níveis, e por que um só não basta

• Unitários e de componente (com Jest ou o equivalente moderno), que verificam lógica e comportamento visível.
• De ponta a ponta (por exemplo, com Playwright), que percorrem os fluxos que pagam as contas: o cadastro, a cotação, o pagamento. O guia de boas práticas do Playwright pede que se teste o que o usuário vê e não os detalhes internos, e que cada teste fique isolado dos demais.
• Acessibilidade e regressão visual. A comparação de capturas ajuda a detectar uma mudança que ninguém abriu, embora a própria documentação do Playwright advirta que a renderização varia conforme o sistema operacional, o navegador e o hardware, e por isso as referências devem ser geradas no mesmo ambiente em que são comparadas.

Sobre acessibilidade, um limite que convém dizer em voz alta: segundo a documentação do Playwright, os testes automáticos detectam alguns problemas comuns, mas muitos só são descobertos com uma revisão manual. Automatize o que for possível e reserve a revisão humana, com teclado e leitor de tela, para os fluxos críticos.

O nível que convém exigir é o WCAG 2.2 AA. Dois exemplos concretos do padrão: o texto deve ter um contraste de pelo menos 4,5:1 (3:1 para texto grande), e os elementos que se tocam ou se clicam devem medir pelo menos 24 por 24 pixels CSS, salvo exceções.

Quantos dos fluxos críticos têm um teste que roda sozinho a cada mudança?

5. CI/CD do frontend: o que deve poder ser interrompido

O pipeline de um frontend é a forma de a qualidade não depender da boa vontade de ninguém. No mínimo, deve verificar estilo, tipos, testes e build, e checar dependências com vulnerabilidades conhecidas (o npm audit envia a descrição das dependências ao registro e devolve um relatório de vulnerabilidades conhecidas; é um controle útil, não uma análise de segurança suficiente por si só). Cada etapa pode interromper a liberação; o detalhe de como se monta um caminho de liberação está em Liberar sem medo na própria infraestrutura.

Sobre a análise de qualidade, o que ela deve cumprir. O portão de qualidade padrão do SonarQube Server, o «Sonar way» (segundo a documentação atual; é a configuração de um produto, não uma definição universal de qualidade), impõe quatro condições sobre o código novo: nenhum problema novo, pontos críticos de segurança revisados, cobertura de pelo menos 80 % e duplicação de 3 % ou menos. O valioso é a filosofia: não se trata de consertar tudo o que é antigo, mas de não acrescentar dívida nova. E um detalhe que nos importa: um portão desligado ou que não é executado não é o mesmo que um portão que passa. É preciso exigir ver a execução, não apenas a cor do painel.

6. SEO e leitura por IA: conteúdo rastreável e verificável

Se o site é público, o conteúdo importante deve ser acessível a um buscador e, quando relevante, a assistentes de IA. É preciso verificar isso no HTML que de fato é entregue e renderizado, e não presumi-lo. O Google recomenda títulos únicos e descritivos e descrições próprias para cada página, e adverte que, se o conteúdo importante fica escondido atrás de JavaScript, pode não ser compreendido. O guia do web.dev sobre estratégias de renderização explica o compromisso: a renderização estática na construção oferece os melhores tempos de resposta, embora escale mal com muitas URLs únicas; a do lado do cliente exige vigiar o peso do JavaScript.

Sobre essa base, três práticas: dados estruturados em JSON-LD (o formato que o Google recomenda por ser o mais fácil de manter em escala), um endereço canônico por página para evitar duplicidades e, se houver vários idiomas, a indicação das versões alternativas por idioma (são dois mecanismos distintos). E uma proposta, o llms.txt, que oferece aos agentes um resumo do site em Markdown. Não é um padrão oficial: é uma proposta aberta da comunidade, e os diferentes agentes de IA se comportam de formas distintas, de modo que não há um requisito universal como o dos buscadores. A melhor condição é que essas verificações façam parte da construção e não de uma lista de que alguém se lembra no final.

7. Desempenho: mede-se com o que o usuário vive

O Google define três sinais de experiência, avaliados no percentil 75 dos carregamentos de página, segmentados entre celular e computador. São medidos com o uso real dos usuários; um teste em uma única máquina orienta, mas não substitui essa medição:

• LCP (a rapidez com que aparece o conteúdo principal): 2,5 segundos ou menos.
• INP (a rapidez com que responde a um toque ou a uma tecla): 200 milissegundos ou menos.
• CLS (o quanto o conteúdo se move enquanto carrega): 0,1 ou menos.

Duas ideias de engenharia sustentam esses números. A primeira: não carregar de saída o que não é usado de saída. O React permite dividir o código e carregar um componente apenas quando é necessário.

// Ilustrativo, tirado da documentação do React (lazy + Suspense).
const VistaPrevia = lazy(() => import('./VistaPrevia.js'));

<Suspense fallback={<Cargando />}>
  <VistaPrevia />
</Suspense>

A segunda: não aplicar essa ideia ao que o usuário vê primeiro. Segundo o web.dev, a imagem candidata a LCP nunca deve ser carregada de forma adiada, porque se atrasa justamente o que esse sinal mede.

8. Segurança: o navegador é território hostil

Tudo o que chega ao navegador é público; nenhum segredo vive ali. Duas ideias centrais:

• XSS. O React escapa por padrão o que é exibido, mas oferece uma via de escape, o dangerouslySetInnerHTML, que a própria documentação chama de perigosa: com conteúdo não confiável, é trivial introduzir uma vulnerabilidade. A OWASP recomenda sanitizar com uma biblioteca especializada e adverte que nenhuma técnica isolada previne o XSS.
• Defesa em profundidade. Uma política de segurança de conteúdo (CSP) restringe o que o código da página pode fazer (de onde carrega recursos e a que se conecta, entre outras coisas) e ajuda contra XSS e clickjacking. A MDN é clara: não substitui a sanitização; é usada além dela.

E uma regra simples de critério: não deixar no navegador, legíveis por qualquer script, credenciais reutilizáveis nem dados sensíveis. E não esquecer que a validação do cliente nunca substitui a do servidor: a autorização é sempre decidida do lado do servidor.

9. Depois de liberar: resiliência e observabilidade

Um frontend profissional parte do princípio de que algo vai falhar. Cada chamada a um serviço tem os estados de carregando, vazio, erro e nova tentativa, e uma falha é exibida, não escondida atrás de uma tela em branco. E alguém precisa saber do erro antes que o cliente o relate: erros do navegador capturados com contexto mínimo e sem dados pessoais, e os sinais de desempenho da seção 7 monitorados com usuários reais. Se o site carrega etiquetas de análise ou de terceiros, elas também são código: pesam no desempenho e devem estar dentro do orçamento.

Também convém acordar o que é suportado: navegadores, dispositivos modestos e redes lentas. Um sistema de design, por fim, precisa de um responsável, de versões e de uma forma de aposentar componentes sem quebrar quem os usa.

Que evidências pedir antes de aprovar

Para um comitê, um frontend se aprova com evidências, não com uma demonstração. Peça: o catálogo de componentes publicado; o relatório dos testes da última liberação, com a contagem lida do resumo; o resultado do portão de qualidade com a condição que falhou, se falhou; a revisão de acessibilidade com a parte manual; os sinais de desempenho com dados reais; e quem autoriza uma exceção e como ela fica registrada.

O que quase toda equipe adia

Duas coisas: os testes de ponta a ponta de todos os fluxos críticos, e que uma falha de acessibilidade interrompa a publicação em vez de apenas avisar. Um controle que não pode interromper uma mudança é uma sugestão. Dizemos isso porque negar não resolve, e porque é justamente o que convém perguntar a qualquer equipe, inclusive à própria.

Encerramento

Um frontend profissional não se reconhece pela aparência no dia da estreia, mas pelo que suporta depois: uma mudança de marca, um auditor, um celular modesto, um buscador, um atacante. Quando isso falha, o custo não é técnico: são vendas perdidas, retrabalho e uma auditoria difícil de superar. Na Hábil somos especialistas nisso. Construímos o frontend do produto com componentes governados, sistema de design, testes, acessibilidade, desempenho e segurança revisados a cada mudança, e podemos começar confrontando a jornada digital prioritária com esta lista.