Engenharia de UI Frontend

Visão Geral

Construa interfaces de usuário de qualidade de produção que sejam acessíveis, performáticas e visualmente polidas. O objetivo é uma UI que pareça ter sido construída por um engenheiro com consciência de design em uma empresa de ponta — não como se tivesse sido gerada por uma IA. Isso significa adesão real ao sistema de design, acessibilidade adequada, padrões de interação pensados e nenhuma "estética de IA" genérica.

Quando Usar

• Construindo novos componentes ou páginas de UI
• Modificando interfaces existentes voltadas para o usuário
• Implementando layouts responsivos
• Adicionando interatividade ou gerenciamento de estado
• Corrigindo problemas visuais ou de UX

Arquitetura de Componentes

Estrutura de Arquivos

Coloque tudo relacionado a um componente junto:

src/components/
  TaskList/
    TaskList.tsx          # Component implementation
    TaskList.test.tsx     # Tests
    TaskList.stories.tsx  # Storybook stories (if using)
    use-task-list.ts      # Custom hook (if complex state)
    types.ts              # Component-specific types (if needed)

Padrões de Componentes

Prefira composição em vez de configuração:

// Good: Composable
<Card>
  <CardHeader>
    <CardTitle>Tasks</CardTitle>
  </CardHeader>
  <CardBody>
    <TaskList tasks={tasks} />
  </CardBody>
</Card>

// Avoid: Over-configured
<Card
  title="Tasks"
  headerVariant="large"
  bodyPadding="md"
  content={<TaskList tasks={tasks} />}
/>

Mantenha os componentes focados:

// Good: Does one thing
export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
  return (
    <li className="flex items-center gap-3 p-3">
      <Checkbox checked={task.done} onChange={() => onToggle(task.id)} />
      <span className={task.done ? 'line-through text-muted' : ''}>{task.title}</span>
      <Button variant="ghost" size="sm" onClick={() => onDelete(task.id)}>
        <TrashIcon />
      </Button>
    </li>
  );
}

Separe a busca de dados da apresentação:

// Container: handles data
export function TaskListContainer() {
  const { tasks, isLoading, error, refetch } = useTasks();

  if (isLoading) return <TaskListSkeleton />;
  if (error) return <ErrorState message="Failed to load tasks" retry={refetch} />;
  if (tasks.length === 0) return <EmptyState message="No tasks yet" />;

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

// Presentation: handles rendering
export function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <ul role="list" className="divide-y">
      {tasks.map(task => <TaskItem key={task.id} task={task} />)}
    </ul>
  );
}

Gerenciamento de Estado

Escolha a abordagem mais simples que funcione:

Local state (useState)           → Component-specific UI state
Lifted state                     → Shared between 2-3 sibling components
Context                          → Theme, auth, locale (read-heavy, write-rare)
URL state (searchParams)         → Filters, pagination, shareable UI state
Server state (React Query, SWR)  → Remote data with caching
Global store (Zustand, Redux)    → Complex client state shared app-wide

Evite "prop drilling" mais profundo que 3 níveis. Se você está passando props por componentes que não as utilizam, introduza contexto ou reestruture a árvore de componentes.

Adesão ao Sistema de Design

Qualidade de UI guiada por referências

Quando o produto precisa de uma direção visual distinta, colete evidências antes de escolher um layout:

1. Pesquise em um catálogo de referências confiável ou use referências fornecidas pela equipe do produto.
2. Estude duas ou três telas relevantes. Registre decisões sobre hierarquia, densidade, navegação, controles, comportamento responsivo e estados de interação.
3. Transforme essas decisões em um pequeno contrato de design antes da implementação. Nomeie a tarefa da tela, a ação principal, os estados necessários, as regras responsivas e os padrões a serem rejeitados.
4. Reconstrua a estrutura útil usando os próprios componentes, tokens, conteúdo e linguagem visual do produto. Nunca copie a marca, o texto proprietário, as imagens ou o layout exato de outro produto.

Use referências como evidência, não como modelos. Se as referências não estiverem disponíveis, documente as suposições e verifique o resultado em relação ao sistema de design existente do produto.

Evite a Estética de IA

UI gerada por IA possui padrões reconhecíveis. Evite todos eles:

…