Imported from promovaweb/specsfy (
specialists/specsfy-specialist-react/SKILL.md). Install upstream withnpx skills add promovaweb/specsfy --skill specsfy-specialist-react. Copyright stays with the author.
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 escolha de Server vs Client Component, cache de dados ou
roteamento de framework; usar
$specsfy-specialist-nextjsnesse caso. - Não acionar para escolher ou adaptar uma biblioteca de componentes visuais
prontos; usar
$specsfy-specialist-ui-componentspara o catálogo e$specsfy-specialist-interfacepara a composição visual. - Combinar com
$specsfy-specialist-typescriptquando o componente expõe props públicas ou modela estado com union discriminada e com$specsfy-specialist-interfacepara auditoria aprofundada de teclado e leitor de tela.
No Specsfy
-
Fonte de entrada por fase
- Em
specsfy-02-backlog, leia o item emspecs/backlog/e registre ali as decisões e sinais do especialista, além das dúvidas abertas. - Em
specsfy-03-specifyespecsfy-04-validate, use a spec aberta e devolva a conclusão à seção trabalhada pela fase. - Em
specsfy-05-tasks, ajude a sugerir e sincronizar especialistas e modos entre o cabeçalho, a seção 8 e as tarefas. Só essa fase escreve a seção 14. - Em
specsfy-06-implement, limite-se à tarefa indicada e ao passo carregado.
Nas fases com spec, leia a spec aberta indicada pela skill chamadora ou localizada por
specsfy status. Consulte a linha| Especialistas |, a subseção#### Especialistasem### 8. Plano técnicoe a seção pertinente à fase. Leia também.specsfy/STACK.mde.specsfy/RULES.mde, quando a tarefa renderizar tela,INTERFACE.md. - Em
-
Siga o modo indicado na spec ou na tarefa, no formato
Especialista: $specsfy-specialist-react. Sem indicação, confirme pelo "Quando usar" acima se o React está instalado antes de assumir a stack. -
Devolva a conclusão e as dúvidas abertas no destino indicado no item 1, no próprio backlog, na spec ou na tarefa da fase.
-
Não mude o estado da spec nem marque gate: isso pertence a
$specsfy-03-specify,$specsfy-04-validate,$specsfy-05-taskse$specsfy-06-implement. -
Confirme telas e estados em
INTERFACE.mde, quando a fase trabalhar o plano técnico da spec, registre o componente, o ownership de estado e o teste correspondente na seção 8 e na estratégia TDD.
Fluxo
- Para uma tela ou formulário, ler
INTERFACE.mde 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-interface; não trocar uma interface pedida por endpoint ou componente vazio. - Confirmar versão do React, renderer, framework (se houver), convenções do
projeto e estratégia de testes já em uso. Registre a geração:
<Activity>euseEffectEventexistem a partir do React 19.2;<ViewTransition>, Fragment refs ebrowser()a partir do 19.3; não proponha esses recursos em projeto 18 sem plano de upgrade. Quando a tela usar shadcn/ui, identificar antes a base de primitives instalada, seguindo$specsfy-specialist-ui-components; nunca deduzir Radix ou Base UI pela aparência do componente. Se.specsfy/STACK.mdnão declarar React ou o projeto não tiver essa dependência, não inicie esta implementação: encaminhe ao especialista da stack observada. - Modelar os estados visíveis (nominal, loading, empty, error, stale, optimistic), os eventos que os produzem e quem é o dono de cada dado.
- Projetar a árvore de componentes com responsabilidades e props pequenas;
preferir composição (
children, slots) a um componente com dezenas de flags booleanas. - Manter cada estado no dono mais próximo capaz de resolvê-lo; derivar
valores durante o render em vez de sincronizar com
useEffect. - 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. Quando a lógica do effect precisa ler o valor mais
recente de props/state sem reconectar a subscription, use
useEffectEvent(React 19.2+); ele não serve para omitir dependência que deveria reexecutar o effect. - Implementar semântica HTML e navegação por teclado antes do acabamento visual; então cobrir com teste de comportamento observável.
- 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.
- Registrar em
INTERFACE.mdcada 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 escolha 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
statesó para "guardar o valor inicial"; isso cria dessincronia: leia a prop diretamente ou derive durante o render. - Não usar
useEffectpara computar um valor derivável de props/state existentes; use uma variável comum ouuseMemoquando 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
keyestá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.Providerpela 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. Com React Compiler habilitado (1.0, integrado ao Next.js 16), a documentação oficial trata a memoização manual como desnecessária na maioria dos casos; mantenhamemo/useMemo/useCallbacksó onde houver medição, restrição do compilador ou componente fora do escopo otimizado. - Preferir
<Activity mode="hidden">(React 19.2+) a desmontar painéis, abas e formulários que a pessoa vai reabrir: ocultar preserva estado e DOM e destrói os effects, então todo efeito com efeito colateral no DOM (mídia, iframe) precisa de cleanup. - 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.
useEffectsem array de dependências completo, "silenciado" com// eslint-disable: esconde bug de closure obsoleta em vez de resolvê-lo.useEffectEventusado para esconder uma dependência real do effect (useEffect(() => log(pageUrl), [])): a documentação do React trata isso como bug escondido, não como otimização.- 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 suposição 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-ui-componentsmantém o catálogo de composições React e Tailwind, identifica a base de primitives instalada e governa os componentes visuais; esta skill governa o comportamento React dentro deles.$specsfy-specialist-interfaceescolhe e compõe a biblioteca visual pronta e aprofunda a auditoria de acessibilidade além do teclado básico validado aqui.$specsfy-specialist-tailwind-cssestiliza o componente sem assumir ownership de estado, effect ou concorrência.$specsfy-specialist-nextjspara fronteira server/client, cache de dados e roteamento: este especialista trata React independente de framework.$specsfy-specialist-typescriptpara tipar props, estado e union discriminada de forma exaustiva.$specsfy-specialist-testingtesta o comportamento visível com Testing Library, sem substituir a definição de estado e composição daqui.
Leia references/standards.md para modelagem de estado, effects, composição, listas, context, testes e performance, com fontes oficiais.
