React y componentes: cómo se construye una interfaz web moderna

Cuando enseñamos a un cliente el sistema de diseño de su web en Figma, hay un momento que siempre nos gusta: abrimos la página de componentes y aparece el botón con todas sus variantes, la tarjeta de producto, el campo de formulario con sus estados de error. Y luego abrimos Storybook, donde esas mismas piezas existen en código, funcionando, con los mismos nombres. «Así que cuando cambiamos el botón aquí, cambia en toda la web», nos dicen. Exactamente. Esa es la idea que hay detrás de React y de la forma moderna de construir interfaces.

Durante años, las webs se programaban página a página. Si el botón aparecía en treinta páginas, se repetía treinta veces, y cambiar su color era una búsqueda en todo el proyecto. Los componentes invierten esa lógica: la interfaz se piensa como un conjunto de piezas con nombre propio, que se definen una vez y se combinan como bloques. React es la herramienta que popularizó esa manera de trabajar, y hoy es la base de buena parte de las interfaces web, incluida la de este estudio.

Esta guía explica cómo funciona sin dar por hecho que programas, y sobre todo cómo conecta con el diseño, que es donde se decide si una interfaz envejece bien.

01Qué es React y qué problema resuelve

React es una librería de JavaScript para construir interfaces. Nació en Facebook para resolver un problema muy concreto: en una interfaz con muchos datos que cambian (notificaciones, comentarios, contadores), mantener la pantalla sincronizada con esos datos a mano era una fuente constante de errores.

Su propuesta es declarativa. En lugar de dar instrucciones paso a paso («busca este elemento, cambia su texto, añade esta clase»), describes cómo debe verse la interfaz para unos datos concretos, y React se encarga de actualizar la pantalla cuando los datos cambian. Es como pasar de dar indicaciones giro a giro a decir la dirección de destino.

Para describir la interfaz se usa JSX, una sintaxis que mezcla JavaScript con algo muy parecido al HTML. A quien diseña le resulta sorprendentemente legible: se reconoce la estructura de la pantalla.

02Componentes: la interfaz como sistema de piezas

Un componente es una función que recibe datos y devuelve un fragmento de interfaz. Puede ser tan pequeño como un icono o tan grande como una página entera, y los componentes se anidan unos dentro de otros. Tres conceptos explican casi todo:

• →Props (propiedades). Los datos que un componente recibe desde fuera, como los parámetros de una función: el texto del botón, la imagen de la tarjeta, la variante de color. Un componente no modifica sus props; las usa.
• →Estado (state). Los datos que un componente recuerda y que pueden cambiar con la interacción: si un menú está abierto, qué pestaña está activa, qué ha escrito alguien en un campo. Cuando el estado cambia, React vuelve a dibujar esa parte de la interfaz.
• →Composición. Los componentes se combinan como bloques. Una tarjeta contiene una imagen, un título y un botón; una rejilla contiene tarjetas. La prop especial children permite que un componente envuelva cualquier contenido.

Así se ve un botón sencillo con variantes, escrito en TypeScript:

type ButtonProps = {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
} & React.ButtonHTMLAttributes<HTMLButtonElement>;
export function Button({ variant = 'primary', size = 'md', children, ...rest }: ButtonProps) {
  return (
    <button className={`btn btn--${variant} btn--${size}`} {...rest}>
      {children}
    </button>
  );
}
// Uso en cualquier pantalla:
// <Button variant="secondary" size="lg" onClick={abrirContacto}>Hablemos</Button>

Fíjate en dos detalles. El componente usa un elemento <button> real, así que el teclado, el foco y los lectores de pantalla funcionan de serie. Y acepta el resto de atributos nativos (...rest), con lo que disabled, type o aria-label funcionan sin programarlos uno a uno.

Una API de variantes clara

La forma de las props es la «API» del componente, y conviene diseñarla con tanto cuidado como su aspecto. Lo que funciona es usar props con valores cerrados que reflejen el sistema de diseño (variant="primary", size="lg") en lugar de acumular booleanos (isBig, isRed, isOutline) que acaban combinándose de formas imposibles. Si en Figma el botón tiene las propiedades Variant y Size, en código deberían llamarse igual. Esa correspondencia es la mitad de un buen traspaso entre diseño y desarrollo.

03Server Components: la parte que ha cambiado las reglas

Durante años, React vivía casi solo en el navegador: se descargaba todo el JavaScript y la interfaz se construía en el dispositivo del usuario. Funcionaba, pero las páginas pesaban y la primera carga se resentía, sobre todo en móviles modestos.

Con React 19, estable desde diciembre de 2024, los Server Components pasaron a ser parte oficial de React, y frameworks como Next.js los usan por defecto. La idea es sencilla y potente:

• →Componentes de servidor. Se ejecutan en el servidor, pueden leer directamente de la base de datos o del CMS y envían al navegador HTML ya resuelto. Su código no llega al navegador, así que no pesan en la descarga.
• →Componentes de cliente. Se marcan con la directiva 'use client' y se ejecutan también en el navegador. Son los que necesitan interacción: un carrusel, un formulario con validación en vivo, un menú desplegable.

El criterio práctico es empezar todo en el servidor y convertir en componente de cliente solo la pieza que necesita interacción, lo más abajo posible en el árbol. Una ficha de producto puede ser casi entera de servidor, con un pequeño componente de cliente para el selector de talla y el botón de añadir. El resultado es mucho menos JavaScript y mejores métricas, algo que desarrollamos en la guía de JavaScript y rendimiento. Cómo se combina esto con el renderizado estático o bajo demanda lo explicamos en la de qué es Next.js.

Otra novedad que ha simplificado el trabajo diario es el React Compiler, estable desde finales de 2025, que optimiza automáticamente cuándo se vuelve a dibujar cada componente. Lo que antes exigía memorizar valores a mano ahora lo resuelve el compilador en la mayoría de casos.

04Del sistema de diseño a la biblioteca de componentes

Aquí es donde el diseño y el código se dan la mano. Una biblioteca de componentes bien hecha es la traducción fiel del sistema de diseño, y se construye en capas, de lo pequeño a lo grande, siguiendo una lógica muy parecida a la del diseño atómico:

1. 01Tokens. Colores, tipografías, espaciados, radios y sombras como variables, generadas desde Figma. Ningún componente usa un color «suelto»; todos beben de los tokens. Lo explicamos en la guía de design tokens.
2. 02Primitivos. Botón, campo de texto, casilla, enlace, icono, etiqueta. Pocas piezas, muy probadas.
3. 03Componentes compuestos. Tarjeta de producto, formulario de contacto, menú de navegación, modal, acordeón.
4. 04Patrones y secciones. Bloques completos que combinan componentes: un hero, una rejilla de proyectos, una sección de preguntas frecuentes.
5. 05Plantillas de página, que ordenan secciones y se llenan con contenido del CMS.

Cada componente se documenta en Storybook, una herramienta que muestra cada pieza aislada con todas sus variantes y estados (normal, foco, desactivado, error, cargando). Es el punto de encuentro entre quien diseña y quien programa: se revisa ahí, antes de verlo dentro de una página.

Estilos: dónde vive el CSS

React no impone cómo se escriben los estilos. Las opciones más habituales son CSS Modules (un archivo CSS por componente, con nombres de clase aislados automáticamente), Tailwind CSS (clases de utilidad configuradas con los tokens del sistema) y CSS moderno con variables, capas y container queries. Todas funcionan; lo importante es elegir una y aplicarla con coherencia. Sea cual sea, los valores salen de los tokens.

05Calidad: cómo se prueba y se mantiene una interfaz de componentes

Una biblioteca de componentes es una inversión que rinde durante años si se cuida. Lo que aplicamos en nuestros proyectos:

• →Tipos con TypeScript. Las props tipadas actúan como documentación viva y detectan errores antes de publicar: si alguien escribe variant="primery", el editor lo marca al momento.
• →Pruebas de componentes con Vitest y Testing Library, que comprueban el comportamiento como lo vería una persona («al pulsar el botón aparece el mensaje de éxito») en lugar de detalles internos.
• →Pruebas visuales que comparan capturas de cada componente en Storybook para detectar cambios no deseados.
• →Pruebas de extremo a extremo con Playwright para los recorridos críticos: contacto, compra, reserva.
• →Auditorías de accesibilidad automáticas con axe en cada componente, complementadas con revisión manual con teclado y lector de pantalla.
• →Nombres compartidos entre Figma y código, y un registro de cambios de la biblioteca para que todo el equipo sepa qué ha cambiado.

06Ejemplo resuelto: una tarjeta de proyecto, de Figma a producción

Para aterrizarlo, así llevamos una tarjeta de proyecto de un portfolio desde el diseño hasta la web:

1. 01En Figma, la tarjeta es un componente con propiedades: Layout (vertical u horizontal), Destacado (sí o no) y una ranura para la imagen. Usa tokens de color, tipografía y espaciado.
2. 02Definimos la API del componente con los mismos nombres: layout, featured, image, title, category, href.
3. 03Decidimos dónde se ejecuta. La tarjeta solo muestra contenido y un enlace: componente de servidor, sin JavaScript en el navegador.
4. 04La construimos con HTML semántico: un <article> con su titular, la imagen con texto alternativo y un único enlace que cubre la tarjeta, para que el lector de pantalla no anuncie tres enlaces repetidos.
5. 05La documentamos en Storybook con sus cuatro combinaciones, en tema claro y oscuro, y con un título muy largo para ver cómo se comporta.
6. 06La revisamos juntos, diseño y desarrollo, en Storybook y en una previsualización de la web. Ajustamos un espaciado y el estado de foco.
7. 07La usamos en la portada, en el listado de proyectos y en los relacionados de cada caso, con datos del CMS.

Cuando meses después decidimos cambiar el tratamiento de la imagen en hover, el cambio se hizo en un solo archivo y llegó a las tres páginas a la vez, revisado en una previsualización antes de publicarse.

07Componentes con criterio humano

React y los componentes son herramientas magníficas, pero lo que hace buena una interfaz sigue siendo el criterio: decidir qué piezas existen, qué variantes tienen sentido, cómo se nombran y cómo se sienten al usarlas. Una biblioteca pequeña y bien pensada vale más que cien componentes que nadie sabe cuándo usar.

En SIMA diseñamos el sistema y lo convertimos en código dentro de nuestros proyectos de desarrollo web y apps, para que diseño y desarrollo hablen el mismo idioma desde el primer día. Si quieres ordenar la interfaz de tu producto en componentes o empezar una web sobre una base sólida, escríbenos y lo hablamos.