specsfy-specialist-react

React

Quando usar

• Acionar quando o pedido envolve componente, hook, context, formulário,

lista, efeito ou estado em React puro (CRA, Vite, RSC-agnóstico).

• Acionar também para revisar por que um componente rerenderiza demais, por

que um efeito roda em loop, ou como decidir onde um estado deve viver.

• Não acionar para decisão de Server vs Client Component, cache de dados ou

roteamento de framework; usar $specsfy-specialist-nextjs nesse caso.

• Não acionar para escolher ou adaptar uma biblioteca de componentes visuais

prontos; usar $specsfy-specialist-react-ui-components com $specsfy-specialist-ui-design para isso.

• Combinar com $specsfy-specialist-typescript quando o componente expõe

props públicas ou modela estado com union discriminada, e com $specsfy-specialist-web-accessibility para auditoria aprofundada de teclado e leitor de tela.

Fluxo

1. Para uma tela ou formulário, ler INTERFACE.md e a seção de interface da spec antes do

código. Confirmar telas, fluxo de informação, campos, validações, padrão de abertura e estados. Se o material não existir, retornar ao $specsfy-specialist-ux-design e $specsfy-specialist-ui-design; não trocar uma interface pedida por endpoint ou componente vazio.

1. Confirmar versão do React, renderer, framework (se houver), convenções do

projeto e estratégia de testes já em uso. Quando a tela usar shadcn/ui, identificar antes a base de primitives instalada, seguindo $specsfy-specialist-shadcn-ui; nunca deduzir Radix ou Base UI pela aparência do componente. Se .specsfy/STACK.md não declarar React ou o projeto não tiver essa dependência, não inicie esta implementação: encaminhe ao especialista da stack observada.

1. Modelar os estados visíveis (nominal, loading, empty, error, stale,

optimistic), os eventos que os produzem e quem é o dono de cada dado.

1. Projetar a árvore de componentes com responsabilidades e props pequenas;

preferir composição (children, slots) a um componente com dezenas de flags booleanas.

1. Manter cada estado no dono mais próximo capaz de resolvê-lo; derivar

valores durante o render em vez de sincronizar com useEffect.

1. Usar effects apenas para sincronizar com um sistema externo (DOM,

subscription, rede, storage) — nunca para computar algo a partir de props e state já disponíveis.

1. Implementar semântica HTML e navegação por teclado antes do acabamento

visual; então cobrir com teste de comportamento observável.

1. Medir performance somente quando houver sintoma real (profiler, métrica de

produção); então memoizar ou dividir o componente com medição registrada, não por precaução.

1. Registrar em INTERFACE.md cada bloco criado, alterado ou reaproveitado:

responsabilidade, arquivo, props, eventos, estados, acessibilidade e telas consumidoras.

Padrões

• Preferir composição a um componente genérico com muitas props de

configuração; dividir quando a árvore de decisão interna cresce.

• Em Laravel com React, usar shadcn/ui para primitives e ReUI para composições

gratuitas. Página e rota compõem blocos React; grade, formulário, filtros, overlays e cartões reutilizáveis são componentes próprios e documentados em INTERFACE.md.

• Nunca copiar uma prop para state só para "guardar o valor inicial"; isso

cria dessincronia — leia a prop diretamente ou derive durante o render.

• Não usar useEffect para computar um valor derivável de props/state

existentes; use uma variável comum ou useMemo quando o cálculo for caro.

• Tornar loading, empty, error, stale e success estados explícitos da UI, não

branches implícitos de um único booleano loading.

• Usar key estável e vinda dos dados (id) em listas; nunca o índice do

array quando a ordem pode mudar, item pode ser removido ou reordenado.

• Isolar cada Context.Provider pela frequência de mudança e responsabilidade

— um context que muda a cada tecla não deve envolver a árvore inteira.

• Não memoizar (memo/useMemo/useCallback) sem medição prévia; memoização

tem custo de comparação e só compensa com renders caros ou comprovadamente frequentes.

• Testar pelo comportamento observável pelo usuário (texto, papel, estado),

nunca por detalhes de implementação de hooks internos.

Antipadrões

• Efeito que sincroniza estado local com uma prop

(useEffect(() => setX(prop), [prop])) — sintoma de estado duplicado; a fonte da verdade já é a prop.

• Cadeia de effects que dispara outro effect via mudança de state

("effect chain") — geralmente colapsa em um único handler de evento ou em cálculo direto durante o render.

• useEffect sem array de dependências completo, "silenciado" com

// eslint-disable — esconde bug de closure obsoleta em vez de resolvê-lo.

• Context único guardando todo o estado global da aplicação ("god context")

— qualquer mudança rerenderiza toda a árvore; prefira contexts menores ou uma biblioteca de estado dedicada quando o grafo de dependências crescer.

• Confundir este escopo com o de $specsfy-specialist-nextjs: adicionar

"use client" em cascata para "resolver" um erro de hook, em vez de mover a interatividade para o componente folha correto.

Validação

• Percorrer a superfície alterada inteira por teclado e testar com leitor de

tela quando houver papel, foco ou anúncio novo.

• Escrever testes para cada estado modelado no passo 2 do Fluxo (nominal,

loading, empty, error, stale, optimistic) e para a recuperação de erro.

• Checar o console por warnings do React (chaves, hooks fora de ordem,

atualização de estado após unmount) e por avisos de hydration quando houver SSR.

• Rodar profiling ou bundle analysis somente quando uma hipótese concreta de

performance existir; anexar a medição antes/depois.

• Não declarar um componente "acessível" ou "performático" sem a comprovação

acima; linguagem absoluta sem prova é proibida.

Skills relacionadas

• $specsfy-specialist-reui para composições React e Tailwind do catálogo

gratuito.

• $specsfy-specialist-astro governa a fronteira da ilha e

$specsfy-specialist-shadcn-ui identifica a base de primitives e governa os componentes visuais; esta skill governa o comportamento React dentro deles.

• $specsfy-specialist-tailwind-css estiliza o componente sem assumir

ownership de estado, effect ou concorrência.

• $specsfy-specialist-nextjs para fronteira server/client, cache de dados e

roteamento — este especialista trata React independente de framework.

• $specsfy-specialist-react-ui-components e $specsfy-specialist-ui-design

para escolher e compor uma biblioteca visual pronta; este especialista entra depois, para ownership de estado, efeitos e testes.

• $specsfy-specialist-typescript para tipar props, estado e union

discriminada de forma exaustiva.

• $specsfy-specialist-web-accessibility para auditoria aprofundada além do

teclado básico validado aqui.

Leia references/standards.md para modelagem de estado, effects, composição, listas, context, testes e performance, com fontes oficiais.