Storybook para documentar componentes

Storybook es una herramienta open source que permite construir componentes de UI de forma aislada, sin necesidad de levantar la aplicación completa. Cada componente se documenta mediante "stories": representaciones de un componente en un estado o variante específica.

Su valor principal es doble. Para desarrolladores, proporciona un entorno de desarrollo rápido donde iterar sobre un componente sin depender del resto de la aplicación. Para equipos de producto y diseño, ofrece un catálogo navegable de todos los componentes disponibles con sus variantes y reglas de uso.

Storybook soporta React, Vue, Angular, Svelte, Web Components y más. La instalación se realiza con un solo comando (npx storybook@latest init) que detecta tu framework y configura todo automáticamente. El resultado es una carpeta .storybook con la configuración y un servidor de desarrollo independiente.

La configuración principal se gestiona en .storybook/main.ts, donde defines qué archivos contienen stories (normalmente *.stories.tsx), qué addons cargar y qué opciones del framework usar. El archivo preview.ts controla los decoradores globales, parámetros por defecto y el tema visual de Storybook.

Una story es una función que devuelve un componente renderizado con un conjunto específico de props. El formato Component Story Format (CSF) es el estándar actual: cada archivo exporta un default meta con la configuración del componente y exports con nombre para cada variante.

Las mejores stories cubren los casos de uso reales del componente, no solo las variantes de props. Incluye stories para estados (loading, error, empty, success), tamaños de viewport, temas (light/dark) y combinaciones con otros componentes. Cada story debería poder entenderse sin leer el código fuente.

Los addons amplían Storybook con funcionalidad que no viene de serie. Los essentials (incluidos por defecto) cubren controles interactivos, documentación automática, viewports, backgrounds y acciones. Más allá de estos, hay addons para accesibilidad, internacionalización, testing y diseño.

Chromatic es la plataforma de testing visual creada por los mantenedores de Storybook. Captura una imagen de cada story en cada build y las compara pixel a pixel con la versión anterior. Cuando detecta un cambio visual, lo marca para revisión humana antes de aprobar o rechazar.

Este flujo es especialmente potente en pull requests: Chromatic comenta en el PR mostrando qué componentes han cambiado visualmente, permitiendo a diseñadores y desarrolladores revisar los cambios antes de hacer merge. Esto elimina las regresiones visuales que pasan desapercibidas en revisiones de código tradicionales.

Storybook se integra en tu pipeline de CI de varias formas. La más básica es ejecutar npx storybook build para generar un sitio estático que puedes desplegar en cualquier hosting. La más avanzada incluye testing visual con Chromatic, tests de interacción con el test-runner de Storybook y checks de accesibilidad automatizados.

Una buena práctica es publicar el Storybook de cada branch como un preview deployment (en Vercel, Netlify o Chromatic) para que diseñadores y product managers puedan revisar los cambios sin levantar nada en local.

Storybook es tan útil como el esfuerzo que inviertas en mantenerlo. Las stories desactualizadas o incompletas generan desconfianza y hacen que los equipos dejen de consultarlo. Trata las stories como parte del definition of done de cada componente: no se considera terminado hasta que sus stories están actualizadas.

Evita crear stories que dependan de datos externos o APIs. Las stories deben ser deterministas y reproducibles. Usa mock data y decoradores para simular contextos (providers, temas, estados de autenticación) sin depender de servicios externos.