react-components

Escreva componentes React semânticos, compostos e focados em marcação — elementos HTML semânticos, telas como composições curtas de componentes com nomes claros, estado e efeitos em hooks enxutos que armazenam apenas fatos e derivam o resto, e lógica de negócio mantida fora do React (veja a habilidade business-logic). Use ao escrever, revisar ou refatorar qualquer componente, hook ou tela React, quando o JSX for uma sopa de divs e strings de classe, quando um componente tiver uma longa sequência de estado e efeitos antes do return, ou quando a lógica estiver embaralhada nos componentes.

O que é react-components?

Esta habilidade define regras para escrever componentes React que são semanticamente corretos, compostos e priorizam a marcação HTML. O objetivo é melhorar a acessibilidade, legibilidade e manutenibilidade do código. As regras incentivam o uso de elementos HTML semânticos (como `main`, `header`, `nav`, `button`) em vez de `divs` genéricas, a composição de telas a partir de componentes com nomes claros e intuitivos, e a separação da lógica de negócio do React através de funções puras e hooks enxutos. A habilidade promove o uso de tipos uniões discriminadas para representar estados mutuamente exclusivos, a delegação de eventos de filhos para pais, e a derivação de dados durante a renderização em vez de armazenamento desnecessário. As plataformas suportadas incluem qualquer projeto React, e a documentação fornece exemplos comparativos de código 'ruim' e 'bom' para cada regra, facilitando a aplicação prática.

Funciona com~Claude Code~Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/tosinamuda/skills/tree/main/react-components

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Componentes React: semânticos, compostos, focados em marcação

Uma tela deve ser legível quanto ao que a compõe, por uma pessoa e por um leitor de tela. Aplique estas regras ao escrever ou alterar componentes React, em qualquer projeto.

  1. Elementos dizem o que são. Use main, header, footer, nav, section, search, ul/li, button, time, form. Um div ou span é apenas para uma caixa que existe para layout ou rolagem.
    // Não assim: toda caixa é um div, então um leitor de tela ouve uma longa sequência de texto, e
    // o "botão" não pode ser alcançado com Tab nem pressionado com Enter.
    <div className="page">
      <div className="top">
        <span className="updated">10:42</span>
        <div className="search"><input placeholder="Pesquisar" /></div>
      </div>
      <div className="group">
        <div className="group-name">Fruta</div>
        <div className="items">
          <div className="item" onClick={add}>Maçãs</div>
        </div>
      </div>
    </div>
    
    // Assim: cada elemento diz o que é, então pontos de referência, listas e botões vêm de graça.
    <main>
      <header>
        <time dateTime="10:42">10:42</time>
        <search><input type="search" aria-label="Pesquisar produtos" /></search>
      </header>
      <section aria-labelledby="fruta">
        <h2 id="fruta">Fruta</h2>
        <ul>
          <li><button type="button" onClick={add}>Maçãs</button></li>
        </ul>
      </section>
    </main>
    
    O que cada escolha proporciona: main e header permitem que um leitor de tela salte entre partes da página; section com seu h2 nomeia a região; ul/li diz "lista, 5 itens"; button é acessível por Tab e pressionado com Enter e Espaço sem código extra; time e search dizem o que seu conteúdo é. Mantenha um div onde nada é significado, como a caixa que rola uma lista lateralmente.
  2. Uma tela é uma composição de partes nomeadas. O JSX de uma tela se lê como um esboço da tela nas próprias palavras do produto: um componente nomeado para cada parte que uma pessoa apontaria. Cada parte é um componente pequeno que possui seu elemento semântico e suas classes, portanto a tela em si não tem tags HTML brutas nem strings de classe. Ler a tela mostra o que há nela; abrir uma parte mostra sua aparência.
    // Não assim: a tela é uma árvore de tags e classes, e o que cada caixa é precisa ser deduzido.
    <div className="flex h-screen flex-col gap-5 pt-7">
      <div className="flex items-center gap-3 px-8">
        <span className="text-gray-500">Loja</span>
        <span className="font-semibold">{storeName}</span>
      </div>
      <div className="min-h-0 flex-1 overflow-y-auto">
        {categories.map((c) => (
          <div key={c.name} className="flex flex-col gap-3">
            <div className="text-2xl font-semibold">{c.name}</div>
            <div className="flex gap-6 overflow-x-auto">{/* cartões de produto */}</div>
          </div>
        ))}
      </div>
      <button className="absolute bottom-2 left-8 rounded-full" onClick={onBack}>←</button>
    </div>
    
    // Assim: a tela são suas partes, nomeadas pelo que são.
    <CatalogLayout heading="Produtos">
      <CatalogHeader>
        <ShopName />
        <StoreName name={storeName} />
      </CatalogHeader>
      <CategoryList categories={categories} onAdd={add} />
      <BackButton label="Voltar para a loja" onBack={onBack} />
    </CatalogLayout>
    
    // Cada parte possui seu próprio elemento e classes, uma vez.
    function CatalogHeader({ children }: { children: ReactNode }) {
      return <header className="flex items-center gap-3 px-8">{children}</header>;
    }
    
    Vale a pena nomear uma parte quando uma pessoa a chamaria de algo ("o cabeçalho", "uma linha de produtos", "o botão voltar"). Um wrapper que existe apenas para espaçamento fica dentro da parte que precisa dele, não na tela.
  3. Nomes que um aluno do segundo ano adivinharia. Use a palavra simples para a coisa: Layout, Header, Row, Card, List, Panel, Button, Margin. Sem metáforas e sem jargão técnico (Frame, Rail, Strip, Gutter, Chrome, Shell), a menos que os próprios usuários do produto usem essa palavra. Teste: alguém que nunca viu o código pode dizer o que <ProductRow> desenha.
    // Não assim: metáfora e jargão que um novato precisa decodificar.
    <PageFrame><TopRail /><ProductStrip gutter={GUTTER} /></PageFrame>
    
    // Assim: a palavra simples para cada coisa.
    <PageLayout><PageHeader /><ProductRow margin={LEFT_MARGIN} /></PageLayout>
    
  4. Marcação primeiro. O corpo de um componente é seu JSX. Mais do que algumas linhas de estado, efeitos ou derivação antes do return vão para um hook nomeado pelo que modela (useProductSearch), que retorna fatos e ações.
    // Não assim: quarenta linhas de estado e efeitos antes de alguém ver o que é desenhado.
    function CatalogScreen({ onAdd }: Props) {
      const [products, setProducts] = useState<Product[] | null>(null);
      const [query, setQuery] = useState("");
      const [adding, setAdding] = useState<string | null>(null);
      useEffect(() => { /* buscar os produtos, proteger contra desmontagem */ }, []);
      const categories = useMemo(() => /* filtrar, depois agrupar */, [products, query]);
      const add = (p: Product) => { /* definir adding, chamar onAdd, capturar */ };
      // ... mais trinta linhas ...
      return <CatalogLayout>...</CatalogLayout>;
    }
    
    // Assim: um hook nomeado pelo que modela, depois o JSX.
    function CatalogScreen({ onAdd }: Props) {
      const search = useProductSearch({ onAdd });
      return (
        <CatalogLayout>
          <CategoryList categories={search.categories} onAdd={search.add} />
        </CatalogLayout>
      );
    }
    
  5. Um estado com tag para visões exclusivas. Quando uma tela mostra exatamente uma de várias coisas, uma função pura ou um hook retorna uma união discriminada que carrega os dados de cada estado, e a tela é um switch exaustivo sobre ele. Sem ternários aninhados e sem cadeia de retornos antecipados.
    // Não assim: uma cadeia de condições, onde a ordem é a lógica e um caso é fácil de perder.
    if (!loaded) return <Spinner />;
    if ("error" in loaded) return <Notice title="Não foi possível carregar o pedido" />;
    if (order.cancelled) return <Notice title="Cancelado" />;
    return order.items.length === 0 ? <EmptyBasket /> : order.paid ? <Receipt /> : <Checkout />;
    
    // Assim: uma função decide e retorna os dados que cada caso precisa.
    type OrderView =
      | { kind: "loading" }
      | { kind: "failed"; error: string }
      | { kind: "cancelled" }
      | { kind: "empty" }
      | { kind: "checkout"; order: Order }
      | { kind: "paid"; order: Order; receipt: Receipt };
    
    const view = useOrderView(id);
    switch (view.kind) {
      case "loading":   return <Spinner />;
      case "failed":    return <Notice title="Não foi possível carregar o pedido" detail={view.error} />;
      case "cancelled": return <Notice title="Cancelado" />;
      case "empty":     return <EmptyBasket />;
      case "checkout":  return <Checkout order={view.order} />;
      case "paid":      return <ReceiptPage order={view.order} receipt={view.receipt} />;
    }
    
    Com kind exaustivo, TypeScript falha na compilação quando um novo caso é adicionado e não é desenhado.
  6. A lógica de negócio vive fora do React. Qualquer coisa que decide, verifica, filtra, ordena ou calcula é uma função pura em um módulo simples que não importa React, para que possa ser reutilizada e testada unitariamente sem renderização. Um hook ou componente a chama; não a contém. Onde esse código vai, como estratificá-lo e como retirá-lo de um componente está na habilidade business-logic.
    // productSearch.ts: sem import React, então executa e é testado por conta própria.
    export function productsMatching(products: readonly Product[], query: string) {
      const words = query.toLowerCase().split(/\s+/).filter(Boolean);
      return products.filter((p) => words.every((w) => p.name.toLowerCase().includes(w)));
    }
    
    // O hook apenas o chama.
    const shown = productsMatching(products, query);
    
  7. Filhos reportam, pais decidem. Props são eventos com fatos (onAdd(product)), nunca um setter do pai.
    // Não assim: o filho recebe os setters do pai e decide o que adicionar significa.
    <ProductCard product={p} setBasket={setBasket} setError={setError} />
    
    // Assim: o filho reporta o que aconteceu, com os fatos; o pai decide.
    <ProductCard product={p} onAdd={() => { add(p); }} />
    
  8. Marcaçao repetida vira um componente na segunda vez que é escrita.
    // Não assim: o mesmo fundo de página e padding escritos em quatro telas.
    <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div>
    
    // Assim: escrito uma vez, na segunda vez que foi necessário.
    <PageLayout>...</PageLayout>
    
  9. Hooks são enxutos e derivam, não armazenam. Um hook mantém apenas o estado que não pode ser computado: o que o usuário fez e o que chegou de fora. Todo o resto é derivado durante a renderização a partir desse estado, pelas funções puras da regra 6. Sem estado que espelha uma prop ou outro estado, e sem efeito que apenas define estado a partir de outro estado. Um efeito é para sincronizar com algo fora do React (uma requisição, um timer, uma assinatura, o DOM) e se limpa. Um hook modela uma coisa.
    // Armazene apenas o que o usuário fez e o que chegou de fora.
    const [query, setQuery] = useState("");
    const { products } = useProducts();                 // buscado; seu efeito se limpa
    
    // Derive o resto a cada renderização, com funções puras de um módulo simples.
    const shown = productsMatching(products, query);
    const empty = shown.length === 0;
    
    // Não assim: uma cópia que se desvia, definida por um efeito que renderiza duas vezes.
    // const [shown, setShown] = useState(products);
    // useEffect(() => { setShown(productsMatching(products, query)); }, [products, query]);
    
  10. Uma divisão não deve alterar o que é desenhado. Grave a marcação renderizada antes e depois e compare; uma suíte de testes bem-sucedida não mostra um wrapper movido.
# Grave a marcação renderizada de cada tela antes da alteração, faça a alteração, grave novamente e compare.
node record-markup.mjs antes/   # seu próprio script Playwright: abre cada estado da tela, salva document.body como HTML
node record-markup.mjs depois/
diff -r antes/ depois/           # apenas os elementos que você pretendia alterar devem diferir

Remova o que muda de execução para execução (ids, horários, códigos gerados) antes de comparar, para que uma diferença real se destaque.

Não divida por dividir: uma tela ainda deve ser legível como um todo, e um componente sem regras não precisa de hook.

Habilidades Relacionadas