Communitygithub.com

Frontend

Use ao construir, revisar ou corrigir UI de navegador, como páginas, componentes, formulários, estado do cliente, gráficos, visualizações de impressão ou PDF, acessibilidade ou desempenho web (Core Web Vitals, tamanho do pacote, renders lentos). Não usar para direção visual, crítica de layout ou marca (use `designer` ou `visual-design`). Não usar para apps nativos ou React Native (use `mobile`).

O que é Frontend?

O skill **Frontend** define padrões rigorosos para interfaces de navegador que pessoas reais utilizam com teclados, leitores de tela, celulares lentos e impressoras. Ele aborda regras frequentemente ignoradas quando a UI "parece pronta", como usar o elemento HTML correto para cada finalidade, garantir que toda visualização assíncrona tenha os quatro estados (carregamento, erro, vazio e dados) e nunca sinalizar informações apenas por cor. O skill também orienta sobre onde cada tipo de estado deve residir (local, compartilhado, URL, servidor), oferece diretrizes para gráficos, impressão e visualizações simplificadas, e estabelece uma ordem de impacto para otimização de desempenho (LCP, INP, CLS). Inclui ainda uma seção de "pegadinhas" com armadilhas comuns (como caminhos de renderização que consomem CPU, propriedades CSS personalizadas não declaradas, e foco em widgets personalizados) e uma lista de verificação prática para garantir que a UI seja acessível, responsiva e livre de erros. O skill é recomendado para tarefas de construção, revisão ou correção de UI de navegador, mas não para decisões visuais (use `designer`), apps nativos (use `mobile`) ou design de API (use `api-design`).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/heliacon/claude-skills/tree/HEAD/skills/frontend

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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 designer e visual-design.
  • iOS nativo, Android ou React Native: o skill mobile (e swift para código Swift).
  • Forma da API e endpoints do servidor: os skills api-design e backend-patterns.
  • Técnica de teste em profundidade: os skills tdd e testing-strategy.

Onde o estado vive

Decida antes de escrever o estado do componente. Comece local e escale apenas por um motivo declarado.

EstadoLarExemplo
UI localEstado do componenteModal aberto, rascunho de input, hover
Compartilhado por irmãosPai comum mais próximoAba ativa lida por dois painéis
Dados do servidorBiblioteca de cache de servidor (TanStack Query, SWR) ou o loader do frameworkRespostas de API, paginação, refetch
Estado do cliente em todo o appUm store pequeno, apenas se necessárioUsuário logado, fila de notificações
Estado de visualização compartilhávelConsulta ou rota da URLFiltros, pesquisa, ID selecionado
Sobrevive a recarregamento, por dispositivolocalStoragePreferê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.md antes de construir ou alterar um gráfico.
  • Impressão ou PDF: leia references/print.md antes 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-mono torna 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ê a var() 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 canvas conflita 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 com innerHTML perde o foco.
  • outline: none sem substituto remove a única pista que usuários de teclado têm. Use :focus-visible para estilizá-lo em vez disso.
  • Botões apenas com ícone precisam de um nome (aria-label ou 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 width e height (ou aspect-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.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

Habilidades Relacionadas