O que Frontend faz?
Padrões para UI de navegador que pessoas reais usam com teclados, leitores de tela, celulares lentos e impressoras. As regras abaixo são aquelas que geralmente são ignoradas quando a UI "parece pronta".
Regras mais importantes
- Use o elemento que significa a coisa.
<button>para ações,<a href>para navegação,<label>para cada campo,<table>para dados tabulares. Uma<div>com um manipulador de clique não é focável, não tem papel e é invisível para tecnologia assistiva. ARIA só preenche lacunas que um elemento nativo não consegue. - Toda visualização assíncrona tem quatro estados: carregamento, erro, vazio e dados. Escreva todos os quatro antes de considerar a visualização pronta. Uma região em branco é um bug.
- Nunca fabrique dados. Um período ausente é uma lacuna ou um rótulo "Sem dados", nunca zero e nunca uma linha interpolada. Previsões são sempre visivelmente distintas dos dados reais.
- Nunca sinalize apenas por cor. Todo status codificado por cor também carrega texto ou um ícone com um nome acessível. Impressão em escala de cinza e leitores daltônicos não recebem nada caso contrário.
- Estado compartilhável vive na URL. Filtros, abas, termos de pesquisa, IDs selecionados. Voltar, recarregar e compartilhar devem mantê-lo. Estado efêmero (hover, uma dica de ferramenta aberta) não vai na URL.
- Um valor derivado de várias partes do estado recebe uma função, chamada sempre que qualquer uma delas mudar. Nunca o calcule dentro do callback que pertence a uma delas. Exemplo: um link de download construído a partir de um corte e um filtro de grupo foi reconstruído apenas no callback de busca do corte, então após uma mudança de filtro a exportação silenciosamente apontou para a lista inteira.
- Refluxo a partir de 320 CSS px para cima. Sem rolagem horizontal na página, sem conteúdo cortado, texto redimensionável até 200%. Teste em largura de telefone e na largura de desktop para a qual você projetou.
- Combine a ferramenta à necessidade. Em um repositório existente, siga o framework e a build já presentes. Para uma pequena página nova ou ferramenta interna, considere HTML, CSS e um pouco de JavaScript antes de adicionar um pipeline de build; recorra a um framework quando o estado genuinamente o exigir.
Quando não usar
- Escolher direção visual, tipografia ou paleta: os skills
designerevisual-design. - iOS nativo, Android ou React Native: o skill
mobile(eswiftpara código Swift). - Forma da API e endpoints do servidor: os skills
api-designebackend-patterns. - Técnica de teste em profundidade: os skills
tddetesting-strategy.
Onde o estado vive
Decida antes de escrever o estado do componente. Comece local e escale apenas por um motivo declarado.
| Estado | Lar | Exemplo |
|---|---|---|
| UI local | Estado do componente | Modal aberto, rascunho de input, hover |
| Compartilhado por irmãos | Pai comum mais próximo | Aba ativa lida por dois painéis |
| Dados do servidor | Biblioteca de cache de servidor (TanStack Query, SWR) ou o loader do framework | Respostas de API, paginação, refetch |
| Estado do cliente em todo o app | Um store pequeno, apenas se necessário | Usuário logado, fila de notificações |
| Estado de visualização compartilhável | Consulta ou rota da URL | Filtros, pesquisa, ID selecionado |
| Sobrevive a recarregamento, por dispositivo | localStorage | Preferências, rascunhos não enviados |
Escale apenas quando: dois componentes não relacionados precisam do mesmo estado (eleve-o ou use o cache do servidor); o estado deve sobreviver a recarregamento (URL ou storage); os dados vêm de um servidor (cache do servidor, não um store global). Dados do servidor copiados para um store global ficam obsoletos e duplicam a lógica de carregamento e erro.
Gráficos, impressão e visualizações simplificadas
- Gráficos: um mapa de cores compartilhado entre front-end e back-end, um estado vazio explícito, lacunas honestas, uma legenda
HTML. Leia
references/charts.mdantes de construir ou alterar um gráfico. - Impressão ou PDF: leia
references/print.mdantes de construir uma visualização para impressão. Canvas não imprimem de forma confiável sem a etapa de captura que ele descreve. - Visualizações simplificadas ou somente leitura para leitores não técnicos: sem controles de edição, texto generoso e tamanhos de alvo, status como cor e palavras, resumos em linguagem simples computados a partir dos dados, poucas telas e números principais com frases curtas em vez de tabelas brutas.
Desempenho
Corrija na ordem de impacto: primeiro waterfalls de requisição, depois JavaScript enviado, depois tempo de resposta do servidor,
depois trabalho na thread principal durante interação e micro-otimização por último. Metas: LCP 2,5s ou menos, INP
200ms ou menos, CLS 0,1 ou menos no percentil 75 das visitas reais. Leia references/performance.md
quando uma página estiver lenta, antes de adicionar uma dependência pesada ou antes de um lançamento com metas de desempenho.
Pegadinhas
- Caminhos de renderização são loops quentes. O corpo de um componente ou um getter computado é executado em cada hover e em cada mudança de estado não relacionada. Derivação pesada ali sufoca a thread principal, e o primeiro sintoma pode ser um teste instável em outro lugar. Deduplicar, depois memoizar nas entradas upstream.
- Uma propriedade CSS personalizada não declarada falha silenciosamente.
var(--mono)quando o token é--font-monotorna a declaração inválida no momento do valor computado: a propriedade herda, sem erro. Em uma propriedade abreviada (font: 400 10px/1 var(--mono)) o tamanho e a altura da linha também são perdidos. Dê avar()um fallback ou verifique os tokens declarados em relação aos referenciados na folha de estilo final. - A altura de um gráfico vai em seu wrapper. Uma altura no
canvasconflita com a lógica de redimensionamento da biblioteca e o gráfico cresce a cada redimensionamento. - Foco é seu trabalho em widgets personalizados. Abrir um diálogo move o foco para dentro dele; fechar retorna o foco para o
gatilho; Escape fecha. Prefira o elemento nativo
<dialog>. Reconstruir marcação cominnerHTMLperde o foco. outline: nonesem substituto remove a única pista que usuários de teclado têm. Use:focus-visiblepara estilizá-lo em vez disso.- Botões apenas com ícone precisam de um nome (
aria-labelou texto oculto visualmente). - Conteúdo que existe apenas após um fetch do cliente é lento em dispositivos fracos, fica em branco quando o JavaScript falha e é mais fraco para rastreadores. Renderize conteúdo significativo no servidor onde a pilha permitir.
- Mídia sem tamanho desloca o layout. Defina
widtheheight(ouaspect-ratio) em imagens, vídeo e embeds. Nunca faça lazy-load da imagem que é o maior elemento acima da dobra. - Menus suspensos, abas e sliders feitos à mão precisam do modelo completo de teclado das Práticas de Autoria WAI-ARIA. Um elemento nativo é quase sempre mais barato.
- Um DOM falso escrito à mão pode tornar os testes inertes. Se o falso retorna um objeto novo por consulta, toda
propriedade escrita nele (
href,disabled,value) é perdida e nenhuma asserção sobre ela pode falhar. Reverta o recurso e exija que o teste falhe antes de confiar nele. - Uma versão fixa de CDN, nunca uma não fixa. Um script não fixado muda sob você sem um commit.
Verificação
Prove com o que o projeto já tem (seu executor de testes, linter, verificador de tipos, ferramentas de acessibilidade) antes de adicionar novas ferramentas.
- Testes, lint e verificação de tipos passam. Qualquer novo teste foi visto falhar com o recurso revertido.
- A página foi renderizada e visualizada, em largura de telefone e largura de desktop. Quando possível, forneça aos revisores uma prévia em execução, bem como capturas de tela.
- Apenas teclado: cada controle acessível, operável e visivelmente focado; ordem corresponde à ordem visual; sem armadilha.
- Uma auditoria automatizada de acessibilidade (axe, Lighthouse ou a ferramenta do projeto) não tem novas violações. Contraste verificado com uma ferramenta: 4,5:1 texto do corpo, 3:1 texto grande e bordas de componentes de UI (WCAG AA).
- Estados de carregamento, erro, vazio e dados foram cada um exibidos, forçando cada um.
- Estado compartilhável sobrevive a recarregamento e volta.
- Console tem zero erros e zero avisos ao carregar e durante o uso.
- Orçamento de desempenho verificado se a mudança adiciona uma dependência ou toca em uma visualização pesada (analisador de pacote, um perfil limitado).
- Prévia de impressão verificada se a página é imprimível.
Para uma revisão, relate descobertas por arquivo com a regra quebrada e a correção, do pior para o melhor.