frontend-dev

---

name: frontend-dev description: Orientação de engenharia frontend de nível sênior, cobrindo arquitetura, design de componentes, desempenho, sistemas de design, integração de API e testes. Use esta skill para QUALQUER tarefa de engenharia frontend: construção de componentes, revisão de arquitetura, configuração de projeto, depuração de desempenho, design de sistema de design, escrita de testes ou integração de APIs. Ative com palavras-chave como "componente", "React", "Angular", "TypeScript", "frontend", "UI", "sistema de design", "desempenho", "bundle", "gerenciamento de estado", "GraphQL", "Relay" ou qualquer trabalho de UI web. Também ative para solicitações vagas como "construa-me uma página" ou "adicione um recurso" quando houver um contexto frontend. Esta skill cobre TODOS os tipos de saída: código, documentos de arquitetura, recomendações de estrutura de arquivos, auditorias de desempenho e estratégias de teste. metadata: version: "1.0.0"

Skill de Desenvolvimento Frontend

Engenharia frontend de nível sênior, pragmática e pronta para produção. O objetivo é sempre código funcional, sustentável e de alto desempenho — não pureza acadêmica.

Detecção de Stack

Antes de qualquer outra coisa, identifique a stack a partir do contexto. Se não estiver claro, pergunte. Em seguida, carregue o arquivo de referência apropriado.

Stack	Carregar
React (sem GraphQL)	references/react.md
React + GraphQL/Relay	references/react-graphql.md
Angular	references/angular.md
TypeScript (todas as stacks)	references/typescript.md (carregar junto com o arquivo da stack)

Sempre carregue references/typescript.md além do arquivo da stack, a menos que o projeto seja explicitamente apenas JS.

---

Princípios Universais

Estes se aplicam independentemente da stack. Não os pule.

Arquitetura

• Separe as preocupações agressivamente: Renderização de UI, lógica de negócios, busca de dados e efeitos colaterais vivem em camadas diferentes. Os componentes não devem conter chamadas de fetch, strings de API brutas ou regras de negócio.
• Co-localize por funcionalidade, não por tipo: Prefira features/user-profile/ contendo componente + hook + teste + estilos em vez de pastas de nível superior components/, hooks/, tests/. Escalone a estrutura de acordo com a complexidade do aplicativo — não superengenharia um aplicativo pequeno.
• Composição em vez de herança: Construa UIs compondo componentes pequenos e focados. Evite hierarquias profundas de componentes.
• Sem abstração prematura: Escreva a coisa duas vezes, depois abstraia. Uma abstração construída em um único caso de uso geralmente está errada.

Design de Componentes

• Os componentes devem fazer uma coisa. Se um componente tiver mais de um motivo para mudar, divida-o.
• Separe componentes de apresentação (UI pura, sem efeitos colaterais) de componentes contêiner/inteligentes (dados, lógica, orquestração).
• As interfaces de props devem ser explícitas e tipadas. Sem any, sem object, sem {} como tipo.
• Padrão para componentes controlados para formulários.

Desempenho (linhas de base não negociáveis)

Metas de Core Web Vitals (medir no percentil 75 de usuários reais):

• LCP ≤ 2,5s (carregamento)
• INP ≤ 200ms (interatividade — substituiu FID em março de 2024)
• CLS ≤ 0,1 (estabilidade visual)

Regras universais de desempenho:

• Nunca bloqueie a thread principal com tarefas síncronas longas
• Carregue lazy routes e componentes pesados por padrão
• Defina dimensões explícitas em todas as imagens e mídia (evita CLS)
• Use fetchpriority="high" em imagens LCP
• Adie scripts de terceiros não críticos
• Evite layout thrashing (agrupe leituras/escritas do DOM)
• Habilite a elegibilidade do bfcache: evite listeners unload, evite no-store onde desnecessário

Sistemas de Design e Tokens

• Defina tokens de design (cor, espaçamento, tipografia, raio, sombra) como a verdade fundamental — nunca codifique valores em componentes
• Use propriedades personalizadas CSS (--color-primary) ou um sistema de tokens (Style Dictionary, configuração Tailwind) para que a tematização seja centralizada
• Atomic Design como modelo mental: átomos → moléculas → organismos → templates → páginas. Não force a nomenclatura, mas pense nesta hierarquia
• Documente componentes no Storybook para isolamento, descoberta e teste de regressão visual
• Acessibilidade não é opcional: WCAG 2.1 AA mínimo. Cada elemento interativo precisa de suporte de teclado, gerenciamento de foco e ARIA onde o HTML semântico é insuficiente

Integração de API

• Nunca chame APIs diretamente dos componentes. Use uma camada de dados: hooks personalizados, serviços ou uma biblioteca de consulta
• Trate todos os três estados explicitamente: carregamento, erro, sucesso — nunca presuma o caminho feliz
• Use atualizações otimistas para desempenho percebido pelo usuário em mutações
• Valide respostas de API no limite (Zod, io-ts ou equivalente) — não confie na forma dos dados externos
• Centralize URLs base de API e injeção de token de autenticação — nunca os espalhe pelos componentes

Estratégia de Testes

Abordagem em três camadas:

1. Testes unitários: Funções puras, utilitários, hooks personalizados (Jest / Vitest)
2. Testes de componente: Comportamento de renderização, interações do usuário, mudanças de estado (Testing Library — teste comportamento, não implementação)
3. Testes E2E: Apenas jornadas críticas do usuário (Playwright ou Cypress)

Regras:

• Teste o comportamento da perspectiva do usuário, não a implementação interna
• Sem snapshots para lógica — eles são frágeis. Use snapshots apenas para regressão visual intencional
• Mire em alta cobertura na lógica de negócios, não em código boilerplate
• Co-localize arquivos de teste com o código que testam: Button.test.tsx ao lado de Button.tsx

Navegação de Código (tsserver)

O fluxo de trabalho geral de LSP sobre busca de texto reside na skill dev-standards ("Navegação de código"). Notas específicas do TypeScript:

A ferramenta LSP roteia para tsserver em TS/TSX. Operações de arquivo único são confiáveis a frio: documentSymbol, hover, goToDefinition.

Ressalva — tsserver indexa preguiçosamente (ao contrário do gopls). Uma consulta entre arquivos (findReferences/workspaceSymbol) executada contra um servidor frio pode silenciosamente subcontar: ele só conhece os arquivos já carregados em seu projeto e retorna um resultado confiante, mas incompleto (por exemplo, apenas a declaração). Defenda-se contra isso:

• Trate uma contagem de referências suspeitamente baixa como não verificada.
• Consulte findReferences de um local de uso (um arquivo que importa o símbolo), não da declaração isoladamente — isso força o grafo do projeto a carregar.
• Para decisões do tipo "isso ainda é usado em algum lugar?" (remoção de código morto, renomeações seguras), confirme com grep — uma subcontagem aqui é perigosa.

Padrões de Ferramentas (2025)

• Empacotador: Vite (padrão para novos projetos); Webpack 5 para grandes configurações empresariais que já o usam
• Linting: ESLint + @typescript-eslint + Prettier (formatação separada do linting)
• Gerenciador de pacotes: pnpm preferido para monorepos; npm ou yarn aceitáveis
• Monorepo: Nx ou Turborepo para workspaces com vários pacotes
• CI: Execute type-check, lint, teste e build em cada PR. Nunca mescle pipelines vermelhos.

---

Modos de Saída

Ao produzir saídas, siga estas diretrizes:

Código de componente: Inclua tipos, trate casos extremos, siga os padrões da stack a partir do arquivo de referência. Forneça o componente + seu teste na mesma resposta, a menos que o tamanho o impeça.

Arquitetura / estrutura de arquivos: Mostre a árvore de diretórios primeiro, depois explique o raciocínio. Seja opinativo — dê uma boa estrutura, não um menu de opções.

Auditoria de desempenho: Liste as descobertas por gravidade (Crítico / Aviso / Informação). Para cada descoberta: o que é, por que importa, como corrigir.

Configuração de sistema de design: Estrutura de tokens primeiro, depois primitivas de componente, depois configuração de documentação.

Integração de API: Mostre o padrão de camada de dados para a stack específica, depois o componente consumindo-a.

Testes: Mostre testes junto com o código sendo testado. Siga AAA (Arrange / Act / Assert).

---

Skill Companheira

Esta skill cobre engenharia. Para estética visual — escolhas tipográficas, sistemas de cor, design de movimento, composição espacial e evitar estéticas genéricas de IA — consulte a skill frontend-design. Em tarefas que exigem ambas (por exemplo, "construa um dashboard que pareça ótimo"), use ambas as skills juntas: frontend-dev para arquitetura e qualidade de código, frontend-design para direção visual.

Arquivos de Referência

Leia estes antes de produzir saída específica da stack:

• references/typescript.md — Modo estrito do TypeScript, padrões, armadilhas comuns
• references/react.md — React 19, Next.js, hooks, gerenciamento de estado, estratégias de renderização
• references/react-graphql.md — Relay, fragmentos co-localizados, padrões GraphQL em React
• references/angular.md — Angular v22, Signals, Componentes Standalone, sem zone, NgRx