CommunityProgramación y desarrollogithub.com

react-componentes

Escribe componentes React semánticos, compuestos y centrados en el marcado — elementos HTML semánticos, pantallas como composiciones cortas de componentes con nombres claros, estado y efectos en hooks delgados que solo almacenan hechos y derivan el resto, y la lógica de negocio mantenida fuera de React (consulta la habilidad business-logic). Úsalo al escribir, revisar o refactorizar cualquier componente, hook o pantalla de React, cuando el JSX sea una sopa de divs y cadenas de clases, cuando un componente tenga una larga secuencia de estado y efectos antes de su return, o cuando la lógica esté enredada en los componentes.

¿Qué es react-componentes?

Esta habilidad proporciona una guía completa para escribir componentes React que sean accesibles, mantenibles y estén correctamente estructurados. Se enfoca en diez reglas clave que promueven el uso de HTML semántico (como `<main>`, `<section>`, `<button>`, etc.) en lugar de `<div>` genéricos, lo que mejora la accesibilidad para lectores de pantalla y la navegación por teclado. Las reglas abarcan desde la composición de pantallas como partes con nombre, el uso de nombres de componentes que cualquier desarrollador junior pueda entender, hasta la separación estricta de la lógica de negocio en funciones puras fuera de React, facilitando las pruebas y el reúso. También recomienda hooks delgados que deriven estado en lugar de almacenar duplicados, el uso de uniones discriminadas para estados de vista excluyentes, y la extracción de componentes cuando el marcado se repite. La habilidad incluye ejemplos de código detallados que comparan malas prácticas con las correctas, y es aplicable a cualquier proyecto React, independientemente del gestor de estado o framework (Next.js, Remix, etc.).

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Componentes React: semánticos, compuestos, centrados en el marcado

Una pantalla debe ser legible como lo que es, tanto para una persona como para un lector de pantalla. Aplica estas reglas al escribir o modificar componentes React, en cualquier proyecto.

  1. Los elementos dicen lo que son. Usa main, header, footer, nav, section, search, ul/li, button, time, form. Un div o span es solo para una caja que existe por diseño o desplazamiento.
    // No así: cada caja es un div, por lo que un lector de pantalla escucha una larga secuencia de texto, y
    // el "botón" no se puede alcanzar con Tab ni presionar con Enter.
    <div className="page">
      <div className="top">
        <span className="updated">10:42</span>
        <div className="search"><input placeholder="Buscar" /></div>
      </div>
      <div className="group">
        <div className="group-name">Fruta</div>
        <div className="items">
          <div className="item" onClick={add}>Manzanas</div>
        </div>
      </div>
    </div>
    
    // Así: cada elemento dice lo que es, por lo que los puntos de referencia, listas y botones vienen gratis.
    <main>
      <header>
        <time dateTime="10:42">10:42</time>
        <search><input type="search" aria-label="Buscar productos" /></search>
      </header>
      <section aria-labelledby="fruit">
        <h2 id="fruit">Fruta</h2>
        <ul>
          <li><button type="button" onClick={add}>Manzanas</button></li>
        </ul>
      </section>
    </main>
    
    Qué aporta cada elección: main y header permiten que un lector de pantalla salte entre partes de la página; section con su h2 nombra la región; ul/li dice "lista, 5 elementos"; button se puede alcanzar con Tab y presionar con Enter y Espacio sin código adicional; time y search indican qué es su contenido. Mantén un div donde no se quiera decir nada, como la caja que desplaza lateralmente una lista.
  2. Una pantalla es una composición de partes con nombre. El JSX de una pantalla se lee como un esquema de la pantalla en las propias palabras del producto: un componente con nombre por cada parte que una persona señalaría. Cada parte es un componente pequeño que posee su elemento semántico y sus clases, por lo que la pantalla en sí no tiene etiquetas HTML sin procesar ni cadenas de clases. Leer la pantalla te dice qué hay en ella; abrir una parte te dice cómo se ve.
    // No así: la pantalla es un árbol de etiquetas y clases, y hay que deducir qué es cada caja.
    <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">Tienda</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">{/* tarjetas de producto */}</div>
          </div>
        ))}
      </div>
      <button className="absolute bottom-2 left-8 rounded-full" onClick={onBack}>←</button>
    </div>
    
    // Así: la pantalla son sus partes, nombradas por lo que son.
    <CatalogLayout heading="Productos">
      <CatalogHeader>
        <ShopName />
        <StoreName name={storeName} />
      </CatalogHeader>
      <CategoryList categories={categories} onAdd={add} />
      <BackButton label="Volver a la tienda" onBack={onBack} />
    </CatalogLayout>
    
    // Cada parte contiene su propio elemento y clases, una vez.
    function CatalogHeader({ children }: { children: ReactNode }) {
      return <header className="flex items-center gap-3 px-8">{children}</header>;
    }
    
    Vale la pena nombrar una parte cuando una persona la llamaría de alguna manera ("el encabezado", "una fila de productos", "el botón de retroceder"). Un contenedor que existe solo para espaciado se queda dentro de la parte que lo necesita, no en la pantalla.
  3. Nombres que un estudiante de segundo año adivinaría. Usa la palabra simple para la cosa: Layout, Header, Row, Card, List, Panel, Button, Margin. Sin metáforas ni jerga técnica (Frame, Rail, Strip, Gutter, Chrome, Shell) a menos que los propios usuarios del producto digan esa palabra. Prueba: alguien que nunca ha visto el código puede decir qué dibuja <ProductRow>.
    // No así: metáfora y jerga que un recién llegado debe descifrar.
    <PageFrame><TopRail /><ProductStrip gutter={GUTTER} /></PageFrame>
    
    // Así: la palabra simple para cada cosa.
    <PageLayout><PageHeader /><ProductRow margin={LEFT_MARGIN} /></PageLayout>
    
  4. Primero el marcado. El cuerpo de un componente es su JSX. Más de unas pocas líneas de estado, efectos o derivación antes del return van a un hook nombrado por lo que modela (useProductSearch), que devuelve hechos y acciones.
    // No así: cuarenta líneas de estado y efectos antes de que alguien pueda ver lo que se dibuja.
    function CatalogScreen({ onAdd }: Props) {
      const [products, setProducts] = useState<Product[] | null>(null);
      const [query, setQuery] = useState("");
      const [adding, setAdding] = useState<string | null>(null);
      useEffect(() => { /* obtener los productos, proteger contra desmontaje */ }, []);
      const categories = useMemo(() => /* filtrar, luego agrupar */, [products, query]);
      const add = (p: Product) => { /* establecer adding, llamar a onAdd, capturar */ };
      // ... treinta líneas más ...
      return <CatalogLayout>...</CatalogLayout>;
    }
    
    // Así: un hook nombrado por lo que modela, luego el JSX.
    function CatalogScreen({ onAdd }: Props) {
      const search = useProductSearch({ onAdd });
      return (
        <CatalogLayout>
          <CategoryList categories={search.categories} onAdd={search.add} />
        </CatalogLayout>
      );
    }
    
  5. Un estado etiquetado para vistas exclusivas. Cuando una pantalla muestra exactamente una de varias cosas, una función pura o un hook devuelve una unión discriminada que lleva los datos de cada estado, y la pantalla es un switch exhaustivo sobre ella. Sin ternarios anidados ni cadenas de retornos tempranos.
    // No así: una cadena de condiciones, donde el orden es la lógica y es fácil pasar por alto un caso.
    if (!loaded) return <Spinner />;
    if ("error" in loaded) return <Notice title="No se pudo cargar el pedido" />;
    if (order.cancelled) return <Notice title="Cancelado" />;
    return order.items.length === 0 ? <EmptyBasket /> : order.paid ? <Receipt /> : <Checkout />;
    
    // Así: una función decide y devuelve los datos que necesita cada caso.
    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="No se pudo cargar el 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} />;
    }
    
    Con kind exhaustivo, TypeScript falla la compilación cuando se añade un nuevo caso y no se dibuja.
  6. La lógica de negocio vive fuera de React. Cualquier cosa que decida, verifique, filtre, ordene o calcule es una función pura en un módulo simple que no importa React, para que pueda reutilizarse y probarse unitariamente sin renderizado. Un hook o componente la llama; no la contiene. Dónde va ese código, cómo estratificarlo y cómo sacarlo de un componente están en la habilidad business-logic.
    // productSearch.ts: sin importar React, por lo que se ejecuta y se prueba por sí solo.
    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)));
    }
    
    // El hook solo lo llama.
    const shown = productsMatching(products, query);
    
  7. Los hijos reportan, los padres deciden. Las props son eventos con hechos (onAdd(product)), nunca un setter del padre.
    // No así: al hijo se le entregan los setters del padre y decide qué significa añadir.
    <ProductCard product={p} setBasket={setBasket} setError={setError} />
    
    // Así: el hijo reporta lo que sucedió, con los hechos; el padre decide.
    <ProductCard product={p} onAdd={() => { add(p); }} />
    
  8. El marcado repetido se convierte en un componente la segunda vez que se escribe.
    // No así: el mismo fondo de página y relleno escritos en cuatro pantallas.
    <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div>
    
    // Así: escrito una vez, la segunda vez que se necesitó.
    <PageLayout>...</PageLayout>
    
  9. Los hooks son delgados y derivan, no almacenan. Un hook guarda solo el estado que no se puede calcular: lo que el usuario hizo y lo que llegó desde fuera. Todo lo demás se deriva durante el renderizado a partir de ese estado, mediante las funciones puras de la regla 6. Sin estado que refleje una prop u otro estado, y sin efecto que solo establezca estado a partir de otro estado. Un efecto es para sincronizar con algo externo a React (una petición, un temporizador, una suscripción, el DOM), y se limpia a sí mismo. Un hook modela una cosa.
    // Almacena solo lo que el usuario hizo y lo que llegó desde fuera.
    const [query, setQuery] = useState("");
    const { products } = useProducts();                 // obtenido; su efecto se limpia
    
    // Deriva el resto en cada renderizado, con funciones puras de un módulo simple.
    const shown = productsMatching(products, query);
    const empty = shown.length === 0;
    
    // No así: una copia que se desvía, establecida por un efecto que renderiza dos veces.
    // const [shown, setShown] = useState(products);
    // useEffect(() => { setShown(productsMatching(products, query)); }, [products, query]);
    
  10. Una división no debe cambiar lo que se dibuja. Registra el marcado renderizado antes y después y compara; un conjunto de pruebas que pasa no muestra un contenedor movido.
# Registra el marcado renderizado de cada pantalla antes del cambio, haz el cambio, registra de nuevo y compara.
node record-markup.mjs before/   # tu propio script de Playwright: abre cada estado de pantalla, guarda document.body como HTML
node record-markup.mjs after/
diff -r before/ after/           # solo los elementos que querías cambiar deberían diferir

Elimina lo que cambia entre ejecuciones (ids, horas, códigos generados) antes de comparar, para que una diferencia real destaque.

No dividas por dividir: una pantalla aún debe ser legible en su conjunto, y un componente sin reglas no necesita un hook.

Skills relacionados