Frontend

Engenharia de Frontend e UI

Visão geral

Construa interfaces com qualidade de produção: acessíveis, performáticas e visualmente polidas. A meta é uma UI que pareça feita por um engenheiro com consciência de design em uma empresa de ponta — não gerada por IA. Isso significa aderência real ao design system, acessibilidade de verdade, padrões de interação bem pensados e nenhuma "estética de IA" genérica.

Quando usar

• Construir novos componentes ou páginas de UI
• Modificar interfaces existentes voltadas ao usuário
• Implementar layouts responsivos
• Adicionar interatividade ou gerenciamento de estado
• Corrigir problemas visuais ou de UX

Quando NÃO usar: trabalho puramente de backend, scripts ou lógica sem superfície visual.

O fluxo

1. Arquitetura de componentes

Estrutura de arquivos — coloque tudo relacionado a um componente junto:

src/components/
  TaskList/
    TaskList.tsx          # Implementação do componente
    TaskList.test.tsx     # Testes
    TaskList.stories.tsx  # Stories do Storybook (se usar)
    use-task-list.ts      # Hook customizado (se o estado for complexo)
    types.ts              # Tipos específicos do componente (se necessário)

Prefira composição a configuração:

// Bom: composável
<Card>
  <CardHeader><CardTitle>Tarefas</CardTitle></CardHeader>
  <CardBody><TaskList tasks={tasks} /></CardBody>
</Card>

// Evite: configurado demais
<Card title="Tarefas" headerVariant="large" bodyPadding="md"
      content={<TaskList tasks={tasks} />} />

Mantenha componentes focados — cada um faz uma coisa. Separe busca de dados de apresentação:

// Contêiner: cuida dos dados
export function TaskListContainer() {
  const { tasks, isLoading, error } = useTasks();

  if (isLoading) return <TaskListSkeleton />;
  if (error) return <ErrorState message="Falha ao carregar tarefas" retry={refetch} />;
  if (tasks.length === 0) return <EmptyState message="Nenhuma tarefa ainda" />;

  return <TaskList tasks={tasks} />;
}

// Apresentação: cuida da renderização
export function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <ul role="list" className="divide-y">
      {tasks.map(task => <TaskItem key={task.id} task={task} />)}
    </ul>
  );
}

2. Gerenciamento de estado

Escolha a abordagem mais simples que funcione:

Estado local (useState)            → Estado de UI específico do componente
Estado elevado                     → Compartilhado entre 2-3 componentes irmãos
Context                            → Tema, auth, idioma (muita leitura, pouca escrita)
Estado na URL (searchParams)       → Filtros, paginação, estado compartilhável
Estado de servidor (React Query, SWR) → Dados remotos com cache
Store global (Zustand, Redux)      → Estado de cliente complexo compartilhado no app

Evite prop drilling com mais de 3 níveis. Se está passando props por componentes que não as usam, introduza um Context ou reestruture a árvore.

3. Aderência ao design system

Evite a estética de IA — UI gerada por IA tem padrões reconhecíveis; evite todos:

Padrão de IA	Por que é problema	Qualidade de produção
Roxo/índigo em tudo	Modelos escolhem paletas "seguras", deixando todo app igual	Use a paleta real do projeto
Gradientes em excesso	Adicionam ruído visual e destoam da maioria dos design systems	Cores chapadas ou gradientes sutis do design system
Tudo arredondado (rounded-2xl)	Arredondamento máximo ignora a hierarquia de raios de borda de designs reais	Border-radius consistente com o design system
Hero sections genéricas	Layout de template sem conexão com o conteúdo ou a necessidade real	Layouts que partem do conteúdo
Texto tipo lorem ipsum	Placeholder esconde problemas de layout que conteúdo real revela (comprimento, quebra, overflow)	Conteúdo de exemplo realista
Padding gigante em tudo	Espaçamento generoso e uniforme destrói a hierarquia visual e desperdiça tela	Escala de espaçamento consistente
Grades de cards padronizadas	Grade uniforme é atalho que ignora prioridade da informação e padrão de leitura	Layouts orientados a propósito
Sombras em camadas	Profundidade que compete com o conteúdo e pesa em dispositivos modestos	Sombras sutis ou nenhuma, salvo se o design system especificar

Espaçamento: use a escala do projeto; não invente valores (padding: 1rem ✓, padding: 13px ✗).

Tipografia: respeite a hierarquia — h1 (título da página, um por página), h2 (seção), h3 (subseção), corpo, texto secundário. Não pule níveis de heading nem use estilo de heading em conteúdo que não é heading.

Cor:

• Use tokens semânticos: text-primary, bg-surface, border-default — não hex cru
• Garanta contraste suficiente (4.5:1 para texto normal, 3:1 para texto grande)
• Não dependa só de cor para transmitir informação (use ícones, texto ou padrões também)

4. Acessibilidade (WCAG 2.1 AA)

Todo componente deve atender: navegação completa por teclado, rótulos ARIA em elementos sem texto visível, gestão de foco quando o conteúdo muda (diálogos, conteúdo dinâmico) e estados vazios/de erro significativos em vez de telas em branco.

Leia referencias/acessibilidade.md somente quando chegar nesta etapa — contém os exemplos de código (teclado, ARIA, foco, estados vazios) e as ferramentas de teste.

5. Design responsivo

Projete mobile-first e depois expanda:

// Tailwind: responsivo mobile-first
<div className="
  grid grid-cols-1      /* Mobile: coluna única */
  sm:grid-cols-2        /* Pequeno: 2 colunas */
  lg:grid-cols-3        /* Grande: 3 colunas */
  gap-4
">

Teste nestes breakpoints: 320px, 768px, 1024px, 1440px.

6. Carregamento e transições

Use skeletons (não spinners) para conteúdo:

function TaskListSkeleton() {
  return (
    <div className="space-y-3" aria-busy="true" aria-label="Carregando tarefas">
      {Array.from({ length: 3 }).map((_, i) => (
        <div key={i} className="h-12 bg-muted animate-pulse rounded" />
      ))}
    </div>
  );
}

Para velocidade percebida, use atualizações otimistas: aplique a mudança no cache local em onMutate, guarde o estado anterior e restaure-o em onError (padrão de rollback do React Query/SWR).

Racionalizações comuns

Racionalização	Realidade
"Acessibilidade é opcional"	É exigência legal em muitas jurisdições e padrão de qualidade de engenharia.
"Deixamos responsivo depois"	Adaptar responsividade depois custa 3x mais que construir desde o início.
"O design não está final, então pulo o estilo"	Use os padrões do design system. UI sem estilo cria primeira impressão quebrada para quem revisa.
"É só um protótipo"	Protótipos viram código de produção. Construa a fundação certa.
"A estética de IA serve por enquanto"	Ela sinaliza baixa qualidade. Use o design system real do projeto desde o início.

Sinais de alerta

• Componentes com mais de 200 linhas (divida)
• Estilos inline ou valores arbitrários em pixels
• Estados de erro, carregamento ou vazio ausentes
• Nenhum teste de navegação por teclado
• Cor como único indicador de estado (vermelho/verde sem texto ou ícone)
• "Cara de IA" genérica (gradientes roxos, cards gigantes, layouts de banco de imagem)

Portão de aprovação

Apresente: a UI funcionando (capturas de tela ou preview) nos estados principais — com dados, vazio, carregando e com erro — e nos breakpoints móvel e desktop, além do resultado da checagem de acessibilidade. O humano aprova: a fidelidade ao design system, o comportamento dos estados e a experiência responsiva. Só avance após aprovação explícita.

Verificação

Após construir a UI:

• O componente renderiza sem erros no console
• Todos os elementos interativos são acessíveis por teclado (percorra a página com Tab)
• O leitor de tela consegue transmitir o conteúdo e a estrutura da página
• Responsivo: funciona em 320px, 768px, 1024px e 1440px
• Estados de carregamento, erro e vazio todos tratados
• Segue o design system do projeto (espaçamento, cores, tipografia)
• Nenhum aviso de acessibilidade nas dev tools ou no axe-core