anubhavg-icpl/vibe

Frontend Sênior

Padrões de desenvolvimento frontend, otimização de performance e ferramentas de automação para aplicações React/Next.js.

Índice

• Estruturação de Projetos
• Geração de Componentes
• Análise de Bundle
• Padrões React
• Otimização Next.js
• Acessibilidade e Testes

---

Estruturação de Projetos

Gere um novo projeto Next.js ou React com TypeScript, Tailwind CSS e configurações de boas práticas.

Fluxo de Trabalho: Criar Novo Projeto Frontend

1. Execute o scaffolder com o nome do seu projeto e template:

   python scripts/frontend_scaffolder.py meu-app --template nextjs
   

2. Adicione funcionalidades opcionais (auth, api, forms, testing, storybook):

   python scripts/frontend_scaffolder.py dashboard --template nextjs --features auth,api
   

3. Navegue até o projeto e instale as dependências:

   cd meu-app && npm install
   

4. Inicie o servidor de desenvolvimento:

   npm run dev
   

Opções do Scaffolder

Opção	Descrição
--template nextjs	Next.js 14+ com App Router e Server Components
--template react	React + Vite com TypeScript
--features auth	Adiciona autenticação NextAuth.js
--features api	Adiciona React Query + cliente API
--features forms	Adiciona React Hook Form + validação Zod
--features testing	Adiciona Vitest + Testing Library
--dry-run	Visualizar arquivos sem criá-los

Estrutura Gerada (Next.js)

meu-app/
├── app/
│   ├── layout.tsx        # Layout raiz com fontes
│   ├── page.tsx          # Página inicial
│   ├── globals.css       # Tailwind + variáveis CSS
│   └── api/health/route.ts
├── components/
│   ├── ui/               # Button, Input, Card
│   └── layout/           # Header, Footer, Sidebar
├── hooks/                # useDebounce, useLocalStorage
├── lib/                  # utils (cn), constants
├── types/                # Interfaces TypeScript
├── tailwind.config.ts
├── next.config.js
└── package.json

---

Geração de Componentes

Gere componentes React com TypeScript, testes e histórias Storybook.

Fluxo de Trabalho: Criar um Novo Componente

1. Gere um componente cliente:

   python scripts/component_generator.py Button --dir src/components/ui
   

2. Gere um componente servidor:

   python scripts/component_generator.py ProductCard --type server
   

3. Gere com arquivos de teste e história:

   python scripts/component_generator.py UserProfile --with-test --with-story
   

4. Gere um hook personalizado:

   python scripts/component_generator.py FormValidation --type hook
   

Opções do Gerador

Opção	Descrição
--type client	Componente cliente com 'use client' (padrão)
--type server	Componente servidor assíncrono
--type hook	Hook React personalizado
--with-test	Incluir arquivo de teste
--with-story	Incluir história Storybook
--flat	Criar no diretório de saída sem subdiretório
--dry-run	Visualizar sem criar arquivos

Exemplo de Componente Gerado

'use client';

import { useState } from 'react';
import { cn } from '@/lib/utils';

interface ButtonProps {
  className?: string;
  children?: React.ReactNode;
}

export function Button({ className, children }: ButtonProps) {
  return (
    <div className={cn('', className)}>
      {children}
    </div>
  );
}

---

Análise de Bundle

Analise o package.json e a estrutura do projeto em busca de oportunidades de otimização de bundle.

Fluxo de Trabalho: Otimizar Tamanho do Bundle

1. Execute o analisador no seu projeto:

   python scripts/bundle_analyzer.py /caminho/para/o/projeto
   

2. Revise a pontuação de saúde e os problemas:

   Pontuação de Saúde do Bundle: 75/100 (C)
   
   DEPENDÊNCIAS PESADAS:
     moment (290KB)
       Alternativa: date-fns (12KB) ou dayjs (2KB)
   
     lodash (71KB)
       Alternativa: lodash-es com tree-shaking
   

3. Aplique as correções recomendadas substituindo dependências pesadas.

4. Execute novamente com modo verboso para verificar padrões de importação:

   python scripts/bundle_analyzer.py . --verbose
   

Interpretação da Pontuação do Bundle

Pontuação	Nota	Ação
90-100	A	Bundle bem otimizado
80-89	B	Otimizações menores disponíveis
70-79	C	Substituir dependências pesadas
60-69	D	Múltiplos problemas precisam de atenção
0-59	F	Problemas críticos de tamanho do bundle

Dependências Pesadas Detectadas

O analisador identifica estes pacotes comuns pesados:

Pacote	Tamanho	Alternativa
moment	290KB	date-fns (12KB) ou dayjs (2KB)
lodash	71KB	lodash-es com tree-shaking
axios	14KB	Fetch nativo ou ky (3KB)
jquery	87KB	APIs DOM nativas
@mui/material	Grande	shadcn/ui ou Radix UI

---

Padrões React

Referência: references/react_patterns.md

Componentes Compostos

Compartilhe estado entre componentes relacionados:

const Tabs = ({ children }) => {
  const [active, setActive] = useState(0);
  return (
    <TabsContext.Provider value={{ active, setActive }}>
      {children}
    </TabsContext.Provider>
  );
};

Tabs.List = TabList;
Tabs.Panel = TabPanel;

// Uso
<Tabs>
  <Tabs.List>
    <Tabs.Tab>Um</Tabs.Tab>
    <Tabs.Tab>Dois</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel>Conteúdo 1</Tabs.Panel>
  <Tabs.Panel>Conteúdo 2</Tabs.Panel>
</Tabs>

Hooks Personalizados

Extraia lógica reutilizável:

function useDebounce<T>(value: T, delay = 500): T {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);

  return debouncedValue;
}

// Uso
const debouncedSearch = useDebounce(searchTerm, 300);

Render Props

Compartilhe lógica de renderização:

function DataFetcher({ url, render }) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch(url).then(r => r.json()).then(setData).finally(() => setLoading(false));
  }, [url]);

  return render({ data, loading });
}

// Uso
<DataFetcher
  url="/api/users"
  render={({ data, loading }) =>
    loading ? <Spinner /> : <UserList users={data} />
  }
/>

---

Otimização Next.js

Referência: references/nextjs_optimization_guide.md

Componentes Servidor vs Cliente

Use Server Components por padrão. Adicione 'use client' apenas quando precisar de:

• Manipuladores de eventos (onClick, onChange)
• Estado (useState, useReducer)
• Efeitos (useEffect)
• APIs do navegador

// Server Component (padrão) - sem 'use client'
async function ProductPage({ params }) {
  const product = await getProduct(params.id);  // Busca no servidor

  return (
    <div>
      <h1>{product.name}</h1>
      <AddToCartButton productId={product.id} />  {/* Componente cliente */}
    </div>
  );
}

// Componente Cliente
'use client';
function AddToCartButton({ productId }) {
  const [adding, setAdding] = useState(false);
  return <button onClick={() => addToCart(productId)}>Adicionar</button>;
}

Otimização de Imagens

import Image from 'next/image';

// Acima da dobra - carregar imediatamente
<Image
  src="/hero.jpg"
  alt="Hero"
  width={1200}
  height={600}
  priority
/>

// Imagem responsiva com fill
<div className="relative aspect-video">
  <Image
    src="/product.jpg"
    alt="Produto"
    fill
    sizes="(max-width: 768px) 100vw, 50vw"
    className="object-cover"
  />
</div>

Padrões de Busca de Dados

// Busca paralela
async function Dashboard() {
  const [user, stats] = await Promise.all([
    getUser(),
    getStats()
  ]);
  return <div>...</div>;
}

// Streaming com Suspense
async function ProductPage({ params }) {
  return (
    <div>
      <ProductDetails id={params.id} />
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews productId={params.id} />
      </Suspense>
    </div>
  );
}

---

Acessibilidade e Testes

Referência: references/frontend_best_practices.md

Checklist de Acessibilidade

1. HTML Semântico: Use elementos apropriados (<button>, <nav>, <main>)
2. Navegação por Teclado: Todos os elementos interativos focalizáveis
3. Rótulos ARIA: Forneça rótulos para ícones e widgets complexos
4. Contraste de Cores: Mínimo 4.5:1 para texto normal
5. Indicadores de Foco: Estados de foco visíveis

// Botão acessível
<button
  type="button"
  aria-label="Fechar diálogo"
  onClick={onClose}
  className="focus-visible:ring-2 focus-visible:ring-blue-500"
>
  <XIcon aria-hidden="true" />
</button>

// Link de pular para usuários de teclado
<a href="#main-content" className="sr-only focus:not-sr-only">
  Pular para o conteúdo principal
</a>

Estratégia de Testes

// Teste de componente com React Testing Library
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('botão dispara ação ao clicar', async () => {
  const onClick = vi.fn();
  render(<Button onClick={onClick}>Clique em mim</Button>);

  await userEvent.click(screen.getByRole('button'));
  expect(onClick).toHaveBeenCalledTimes(1);
});

// Teste de acessibilidade
test('diálogo é acessível', async () => {
  render(<Dialog open={true} title="Confirmar" />);

  expect(screen.getByRole('dialog')).toBeInTheDocument();
  expect(screen.getByRole('dialog')).toHaveAttribute('aria-labelledby');
});

---

Referência Rápida

Configuração Comum do Next.js

// next.config.js
const nextConfig = {
  images: {
    remotePatterns: [{ hostname: "cdnexamplecom" }],
    formats: ['image/avif', 'image/webp'],
  },
  experimental: {
    optimizePackageImports: ['lucide-react', '@heroicons/react'],
  },
};

Utilitários Tailwind CSS

// Classes condicionais com cn()
import { cn } from '@/lib/utils';

<button className={cn(
  'px-4 py-2 rounded',
  variant === 'primary' && 'bg-blue-500 text-white',
  disabled && 'opacity-50 cursor-not-allowed'
)} />

Padrões TypeScript

// Props com children
interface CardProps {
  className?: string;
  children: React.ReactNode;
}

// Componente genérico
interface ListProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
}

function List<T>({ items, renderItem }: ListProps<T>) {
  return <ul>{items.map(renderItem)}</ul>;
}

---

Recursos

• Padrões React: references/react_patterns.md
• Otimização Next.js: references/nextjs_optimization_guide.md
• Melhores Práticas: references/frontend_best_practices.md
• Biblioteca de perguntas forçadas (grill de Matt Pocock): references/forcing_questions.md
• Mapa de composição (para qual especialista bifurcar): references/composition_map.md

---

Suposições e Critérios de Sucesso Verificáveis (disciplina Karpathy)

Antes que esta habilidade estruture um componente, recomende um framework ou audite um bundle, as seguintes quatro suposições DEVEM ser explicitadas.

1. Dispositivo primário do usuário + rede — mobile-4G, desktop-fibra, Android de baixo custo ou rede corporativa. Conduz cada decisão de perf.
2. Meta de LCP em milissegundos — um único número, não "rápido". Conduz o orçamento do bundle e a escolha de renderização.
3. Dependente de SEO vs. protegido por autenticação — conduz a renderização (SSR/SSG/RSC vs. SPA).
4. Meta WCAG + proprietário nomeado de a11y — AA, AAA ou melhor esforço. Conduz o investimento em a11y e os gates de CI.

Critérios de sucesso verificáveis (Karpathy #4) — toda recomendação deve incluir:

• Metas de Core Web Vitals (LCP, INP, CLS) no p75 no dispositivo primário
• Um orçamento de bundle JS por rota em KB-gzip
• Um piso de a11y no Lighthouse + piso de perf

Se qualquer um desses três não for declarado, a recomendação está incompleta — retorne ao Q2 da biblioteca de perguntas forçadas.

A ferramenta scripts/frontend_decision_engine.py codifica essas verificações: ela se recusa a recomendar um perfil sem as quatro entradas de suposição e imprime os limites verificáveis para o perfil correspondente.

---

Perfis de Personalização

Quatro perfis integrados em profiles/ calibram todas as recomendações:

Perfil	Quando escolher	Meta LCP (mobile-4G p75)	Orçamento de bundle
next-app-router	SaaS voltado para o cliente, SEO + dinâmico, RSC-first	2000ms	150 KB-gzip / rota
remix-or-sveltekit	Mobile-4G primário, low-JS-first, aprimoramento progressivo	1500ms	80 KB-gzip / rota
vite-spa	App protegido por autenticação, desktop/corporativo primário	2500ms	200 KB init + 80 KB / rota
astro-or-static	Marketing / docs / blog, escrita quase zero, SEO crítico	1200ms	30 KB JS / página

Escolha um perfil via:

python scripts/frontend_decision_engine.py \
  --primary-device mobile-4g --lcp-target-ms 2000 \
  --seo-dependent true --auth-walled false --team-size 5

A ferramenta retorna o perfil de melhor ajuste, o trade-off do segundo colocado (se dentro de 15%), as escolhas de stack, os anti-padrões a evitar naquele perfil e os gates de CI necessários.

Para adicionar um perfil personalizado (por exemplo, os padrões de ferramenta interna da sua organização): copie profiles/vite-spa.json para profiles/<sua-org>.json e ajuste constraints + success_thresholds.

---

Mapa de Composição

Esta habilidade NÃO reimplementa o escopo pertencente aos especialistas de nível POWERFUL. Ela bifurca neles. Consulte references/composition_map.md para a tabela de roteamento completa. Bifurcações principais:

Preocupação	Bifurcar em
Auditoria WCAG, contraste, leitor de tela	engineering-team/skills/a11y-audit/
Perfil de bundle + perf em tempo de execução	engineering/skills/performance-profiler/
Landing cinematográfica / narrativa com scroll	engineering-team/skills/epic-design/
Apple HIG (iOS / macOS / visionOS)	product-team/skills/apple-hig-expert/
Revisão Karpathy pré-commit	engineering/karpathy-coder/
Grill de arquitetura pré-execução	engineering/grill-me/

O agente cs-frontend-engineer orquestra essas bifurcações via context: fork. Invoque-o de outro agente com Agent({subagent_type: "cs-frontend-engineer", prompt: "..."}) ou via /cs:frontend-rev.