composants-react

Écrire des composants React sémantiques, composés et centrés sur le balisage — éléments HTML sémantiques, écrans comme des compositions courtes de composants nommés simplement, état et effets dans des hooks fins qui ne stockent que des faits et dérivent le reste, et logique métier maintenue en dehors de React (voir la compétence business-logic). À utiliser lors de l'écriture, la révision ou le refactoring de tout composant, hook ou écran React, lorsque le JSX est une soupe de divs et de chaînes de classes, lorsqu'un composant a une longue série d'état et d'effets avant son return, ou lorsque la logique est enchevêtrée dans les composants.

Qu'est-ce que composants-react ?

Cette compétence définit des règles strictes pour écrire des composants React sémantiques, accessibles et maintenables. Elle met l'accent sur l'utilisation d'éléments HTML sémantiques (comme `main`, `header`, `section`, `button`, `time`, `search`) pour améliorer l'accessibilité et la lisibilité du code. Les écrans doivent être composés de petites parties nommées de manière descriptive, chacune possédant son propre élément sémantique et ses classes, ce qui rend la structure de l'écran évidente à la lecture. La logique métier est extraite dans des fonctions pures dans des modules séparés, sans import React, pour faciliter les tests et la réutilisation. Les hooks sont fins et dérivent l'état plutôt que de le stocker redondamment, en utilisant des unions discriminées pour les vues exclusives. La compétence s'applique à tout projet React et fournit des exemples concrets de transformation de code non sémantique en code sémantique.

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

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Composants React : sémantiques, composés, centrés sur le balisage

Un écran doit être lisible tel qu'il est constitué, par une personne et par un lecteur d'écran. Appliquez ces règles lors de l'écriture ou de la modification de composants React, dans n'importe quel projet.

  1. Les éléments disent ce qu'ils sont. Utilisez main, header, footer, nav, section, search, ul/li, button, time, form. Un div ou un span n'est que pour une boîte qui existe pour la mise en page ou le défilement.
    // Pas ça : chaque boîte est un div, donc un lecteur d'écran entend un long texte continu, et
    // le "bouton" ne peut pas être atteint avec Tab ni activé avec Entrée.
    <div className="page">
      <div className="top">
        <span className="updated">10:42</span>
        <div className="search"><input placeholder="Rechercher" /></div>
      </div>
      <div className="group">
        <div className="group-name">Fruit</div>
        <div className="items">
          <div className="item" onClick={add}>Pommes</div>
        </div>
      </div>
    </div>
    
    // Ceci : chaque élément dit ce qu'il est, donc les points de repère, les listes et les boutons viennent gratuitement.
    <main>
      <header>
        <time dateTime="10:42">10:42</time>
        <search><input type="search" aria-label="Rechercher des produits" /></search>
      </header>
      <section aria-labelledby="fruit">
        <h2 id="fruit">Fruit</h2>
        <ul>
          <li><button type="button" onClick={add}>Pommes</button></li>
        </ul>
      </section>
    </main>
    
    Ce que chaque choix apporte : main et header permettent à un lecteur d'écran de naviguer entre les parties de la page ; section avec son h2 nomme la région ; ul/li dit "liste, 5 éléments" ; button est accessible par Tab et activé par Entrée et Espace sans code supplémentaire ; time et search disent ce que leur contenu est. Gardez un div là où rien n'est signifié, comme la boîte qui fait défiler une liste horizontalement.
  2. Un écran est une composition de parties nommées. Le JSX d'un écran se lit comme un plan de l'écran dans les propres mots du produit : un composant nommé pour chaque partie qu'une personne pointerait. Chaque partie est un petit composant qui possède son élément sémantique et ses classes, de sorte que l'écran lui-même n'a pas de balises HTML brutes ni de chaînes de classes. Lire l'écran vous dit ce qu'il contient ; ouvrir une partie vous dit à quoi elle ressemble.
    // Pas ça : l'écran est un arbre de balises et de classes, et ce qu'est chaque boîte doit être déduit.
    <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">Boutique</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">{/* cartes produit */}</div>
          </div>
        ))}
      </div>
      <button className="absolute bottom-2 left-8 rounded-full" onClick={onBack}>←</button>
    </div>
    
    // Ceci : l'écran est ses parties, nommées pour ce qu'elles sont.
    <CatalogLayout heading="Produits">
      <CatalogHeader>
        <ShopName />
        <StoreName name={storeName} />
      </CatalogHeader>
      <CategoryList categories={categories} onAdd={add} />
      <BackButton label="Retour à la boutique" onBack={onBack} />
    </CatalogLayout>
    
    // Chaque partie possède son propre élément et ses classes, une fois.
    function CatalogHeader({ children }: { children: ReactNode }) {
      return <header className="flex items-center gap-3 px-8">{children}</header>;
    }
    
    Une partie mérite d'être nommée quand une personne l'appellerait quelque chose ("l'en-tête", "une rangée de produits", "le bouton retour"). Un wrapper qui n'existe que pour l'espacement reste à l'intérieur de la partie qui en a besoin, pas dans l'écran.
  3. Noms qu'un étudiant de deuxième année devinerait. Utilisez le mot simple pour la chose : Layout, Header, Row, Card, List, Panel, Button, Margin. Pas de métaphore et pas de jargon professionnel (Frame, Rail, Strip, Gutter, Chrome, Shell) sauf si les propres utilisateurs du produit disent ce mot. Test : quelqu'un qui n'a jamais vu le code peut dire ce que <ProductRow> dessine.
    // Pas ça : métaphore et jargon qu'un nouveau venu doit décoder.
    <PageFrame><TopRail /><ProductStrip gutter={GUTTER} /></PageFrame>
    
    // Ceci : le mot simple pour chaque chose.
    <PageLayout><PageHeader /><ProductRow margin={LEFT_MARGIN} /></PageLayout>
    
  4. Balisage d'abord. Le corps d'un composant est son JSX. Plus de quelques lignes d'état, d'effets ou de dérivation avant le return vont dans un hook nommé pour ce qu'il modélise (useProductSearch), qui retourne des faits et des actions.
    // Pas ça : quarante lignes d'état et d'effets avant que quiconque puisse voir ce qui est dessiné.
    function CatalogScreen({ onAdd }: Props) {
      const [products, setProducts] = useState<Product[] | null>(null);
      const [query, setQuery] = useState("");
      const [adding, setAdding] = useState<string | null>(null);
      useEffect(() => { /* récupérer les produits, se protéger contre le démontage */ }, []);
      const categories = useMemo(() => /* filtrer, puis grouper */, [products, query]);
      const add = (p: Product) => { /* définir adding, appeler onAdd, attraper */ };
      // ... trente lignes de plus ...
      return <CatalogLayout>...</CatalogLayout>;
    }
    
    // Ceci : un hook nommé pour ce qu'il modélise, puis le JSX.
    function CatalogScreen({ onAdd }: Props) {
      const search = useProductSearch({ onAdd });
      return (
        <CatalogLayout>
          <CategoryList categories={search.categories} onAdd={search.add} />
        </CatalogLayout>
      );
    }
    
  5. Un état étiqueté pour les vues exclusives. Lorsqu'un écran affiche exactement une chose parmi plusieurs, une fonction pure ou un hook retourne une union discriminée qui porte les données de chaque état, et l'écran est un switch exhaustif dessus. Pas de ternaires imbriqués et pas de chaîne de retours anticipés.
    // Pas ça : une chaîne de conditions, où l'ordre est la logique et un cas est facile à manquer.
    if (!loaded) return <Spinner />;
    if ("error" in loaded) return <Notice title="Impossible de charger la commande" />;
    if (order.cancelled) return <Notice title="Annulée" />;
    return order.items.length === 0 ? <EmptyBasket /> : order.paid ? <Receipt /> : <Checkout />;
    
    // Ceci : une fonction décide et retourne les données dont chaque cas a besoin.
    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="Impossible de charger la commande" detail={view.error} />;
      case "cancelled": return <Notice title="Annulée" />;
      case "empty":     return <EmptyBasket />;
      case "checkout":  return <Checkout order={view.order} />;
      case "paid":      return <ReceiptPage order={view.order} receipt={view.receipt} />;
    }
    
    Avec kind exhaustif, TypeScript échoue la construction lorsqu'un nouveau cas est ajouté et non dessiné.
  6. La logique métier vit en dehors de React. Tout ce qui décide, vérifie, filtre, trie ou calcule est une fonction pure dans un module simple qui n'importe pas React, afin qu'elle puisse être réutilisée et testée unitairement sans rendu. Un hook ou un composant l'appelle ; il ne la contient pas. Où va ce code, comment le superposer et comment le sortir d'un composant sont dans la compétence business-logic.
    // productSearch.ts : pas d'import React, donc il s'exécute et est testé tout seul.
    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)));
    }
    
    // Le hook ne fait que l'appeler.
    const shown = productsMatching(products, query);
    
  7. Les enfants rapportent, les parents décident. Les props sont des événements avec des faits (onAdd(product)), jamais un setter du parent.
    // Pas ça : l'enfant reçoit les setters du parent et décide ce que signifie ajouter.
    <ProductCard product={p} setBasket={setBasket} setError={setError} />
    
    // Ceci : l'enfant rapporte ce qui s'est passé, avec les faits ; le parent décide.
    <ProductCard product={p} onAdd={() => { add(p); }} />
    
  8. Un balisage répété devient un composant la deuxième fois qu'il est écrit.
    // Pas ça : le même fond de page et le même remplissage écrits dans quatre écrans.
    <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div>
    
    // Ceci : écrit une fois, la deuxième fois qu'il était nécessaire.
    <PageLayout>...</PageLayout>
    
  9. Les hooks sont fins et dérivent, ne stockent pas. Un hook ne garde que l'état qui ne peut pas être calculé : ce que l'utilisateur a fait et ce qui est arrivé de l'extérieur. Tout le reste est dérivé pendant le rendu à partir de cet état, par les fonctions pures de la règle 6. Pas d'état qui reflète une prop ou un autre état, et pas d'effet qui ne fait que définir un état à partir d'un autre état. Un effet est pour se synchroniser avec quelque chose en dehors de React (un fetch, un minuteur, un abonnement, le DOM), et se nettoie après lui-même. Un hook modélise une chose.
    // Stockez seulement ce que l'utilisateur a fait et ce qui est arrivé de l'extérieur.
    const [query, setQuery] = useState("");
    const { products } = useProducts();                 // récupéré ; son effet se nettoie
    
    // Dérivez le reste à chaque rendu, avec des fonctions pures d'un module simple.
    const shown = productsMatching(products, query);
    const empty = shown.length === 0;
    
    // Pas ça : une copie qui dérive, définie par un effet qui rend deux fois.
    // const [shown, setShown] = useState(products);
    // useEffect(() => { setShown(productsMatching(products, query)); }, [products, query]);
    
  10. Une scission ne doit pas changer ce qui est dessiné. Enregistrez le balisage rendu avant et après et comparez ; une suite de tests réussie ne montre pas un wrapper déplacé.
# Enregistrez le balisage rendu de chaque écran avant le changement, faites le changement, enregistrez à nouveau, et comparez.
node record-markup.mjs before/   # votre propre script Playwright : ouvre chaque état d'écran, sauvegarde document.body sous forme de HTML
node record-markup.mjs after/
diff -r before/ after/           # seuls les éléments que vous vouliez changer doivent différer

Supprimez ce qui change d'une exécution à l'autre (ids, heures, codes générés) avant de comparer, afin qu'une vraie différence se démarque.

Ne scindez pas pour le plaisir : un écran doit toujours être lisible dans son ensemble, et un composant sans règles n'a besoin d'aucun hook.

Skills associés