Biblioteca de componentes y Storybook

Por qué una web de marketing tiene su propia librería de componentes

Un portfolio no necesita un design system para renderizar. La razón para construirlo de todos modos es la misma por la que lo merece un proyecto de cliente: en cuanto más de una página comparte un botón, una decisión de color o una curva de animación, la UI sin documentar se convierte en deuda que alguien paga después. Esta librería es pequeña a propósito — diez primitivas, de Button a un Carousel con scroll-snap — pero se gestiona con el rigor que aplicaría a un sistema de producto de cincuenta componentes, y es el sistema con el que este sitio está construido de verdad.

Las decisiones viven donde se leen

Cada story abre con la decisión de diseño que codifica, no con una tabla de props pelada. Button documenta por qué se eliminó la variante ghost y su papel pasó al patrón de enlace semántico. Badge documenta que sus variantes mapean una a una con la taxonomía project_type de WordPress, de modo que el CMS gobierna el color de cada tarjeta sin pegamento de traducción. Tag está documentado como lo que es — un alias legible de la misma geometría de chip, que se conserva porque el código de uso se lee mejor, no porque sea un segundo chip. Cuando una decisión cambia, la story es el changelog.

Tokens antes que colores

Los componentes hablan una capa semántica — ink, surface, line, accent — en lugar de nombres de paleta en crudo. Esa capa es la que convirtió el rebranding de este sitio en una edición de tokens en vez de un buscar-y-reemplazar por una veintena de ficheros, y mantiene honesta la documentación: Storybook carga la hoja de estilos de producción, así que un token cambiado en la aplicación cambia en la documentación en el mismo segundo.

Documentación que no puede desincronizarse

Storybook corre sobre Vite, desacoplado a propósito del runtime de Next.js — la única dependencia de Next en juego está aliaseada a un mock de ancla plana, de modo que una actualización del framework no puede romper la documentación. La tipografía es la misma idea a la inversa: la aplicación carga sus fuentes mediante variables CSS de next/font, y la preview de Storybook define variables idénticas, así que el tipo se resuelve igual en ambas. El contenido también es real: las stories de Timeline y CertificationCard importan los datos reales del CV desde el mismo módulo que usa la página About. Sin lorem ipsum, sin fixtures que se quedan viejos.

La accesibilidad como restricción de trabajo

El addon de a11y ejecuta comprobaciones automáticas en cada story, pero las decisiones que merecen nombrarse son manuales. Los puntos del carrusel móvil son botones reales sobre áreas táctiles de 32px con foco de teclado visible. Su píldora activa cambia de color sobre superficies oscuras, porque el acento sobre slate-900 mide 2,6:1 — por debajo de cualquier suelo de contraste aceptable. Las animaciones de aparición van detrás de una red de seguridad de prefers-reduced-motion. Ninguna herramienta automática señala nada de esto; hay que diseñarlo.

Qué puedes verificar

• Abre la página de docs de cualquier componente — la decisión de diseño, y cuándo no usar el componente, están escritas arriba.
• Recorre con el tabulador la story del Carousel — los puntos reciben foco de teclado y anuncian su posición.
• Activa el panel de accesibilidad en cualquier story y lee las comprobaciones automáticas.
• Compara un componente aquí con el sitio en producción — mismos tokens, mismas fuentes, mismos datos, porque son la misma fuente.

Qué se transfiere a un proyecto de cliente

El tamaño del sistema no es lo importante; la disciplina sí. Tokens antes que colores, decisiones documentadas junto a los componentes a los que dan forma, accesibilidad tratada como restricción y no como casilla, y documentación cableada para que no pueda pudrirse en silencio. Ese enfoque encaja sin cambios en una tienda WooCommerce o en un design system editorial — lo único que escala es el número de componentes.