Disponibilidade de material de apoio

Esta cópia do catálogo contém as orientações inline abaixo, mas não inclui os seguintes caminhos de suporte. São pré-requisitos externos, não arquivos agrupados:

• <support-root>/references/accessibility-checklist.md

Obtenha o material necessário da fonte upstream declarada, ou de uma instalação fornecida pelo usuário dessa fonte. Resolva cada caminho em relação a essa instalação, inspecione seu conteúdo e verifique quaisquer licenças aplicáveis e pré-requisitos de execução. Não execute um comando ou reivindique que um procedimento referenciado foi seguido até que seu arquivo necessário exista. Não fabrique os scripts ausentes ou trate um arquivo não relacionado com o mesmo nome como equivalente. Etapas independentes totalmente documentadas aqui podem prosseguir dentro do escopo autorizado do usuário; relate qualquer etapa dependente como indisponível.

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 aderência 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 } = 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ê estiver passando props por componentes que não as utilizam, introduza contexto ou reestruture a árvore de componentes.

Aderência ao Sistema de Design

Evite a Estética de IA

Interfaces geradas por IA têm padrões reconhecíveis. Evite todos eles:

…