Instalar Storybook es el primer paso para construir un design system sólido y documentado, y este recorrido te muestra cómo hacerlo desde cero usando Vanilla JavaScript. Aprenderás a configurar la herramienta, entender su estructura de carpetas y reconocer los archivos clave que dan vida a cada componente.

Esta guía está pensada para desarrolladores frontend que quieren centralizar componentes reutilizables, documentarlos y probarlos visualmente sin depender de un framework como React, Vue o Angular.

¿Cómo se instala Storybook desde la documentación oficial?

La instalación arranca en la documentación oficial de Storybook, porque ahí encuentras las pautas exactas según el framework que uses. En este caso, el framework elegido es HTML, ya que el curso trabaja con Vanilla JavaScript [01:30].

Para instalarlo, sigue estos pasos:

1. Entra a storybook.js.org y ve a la sección de Guías.
2. Selecciona HTML como framework de trabajo.
3. Copia el comando npx que aparece en la documentación.
4. Pégalo en tu terminal dentro de la carpeta del proyecto.
5. Cuando aparezca la pregunta durante la instalación, presiona Y para continuar.

Al terminar, Storybook te indica que ejecutes npm run storybook para iniciar el entorno [03:25].

¿Qué hace el comando npx de Storybook? Detecta tu proyecto, instala las dependencias necesarias y crea la estructura inicial con componentes de ejemplo, archivos de configuración y carpetas de historias listas para usar.

¿En qué puerto corre Storybook por defecto?

Una vez ejecutado el comando, Storybook abre automáticamente una ventana en tu navegador en localhost:6006. Ese es el puerto donde vas a visualizar todos tus componentes mientras desarrollas [04:10].

¿Qué encuentras en la interfaz de Storybook al iniciar?

La interfaz se divide en tres zonas principales que te permiten interactuar con cada componente: un menú lateral con la lista de historias, un panel central de previsualización y un panel inferior de controles.

En el menú lateral verás componentes de ejemplo como botones, headers y páginas. Al hacer clic en un botón, aparece renderizado a la derecha y abajo se despliegan los controls, que funcionan como variantes manipulables en tiempo real [05:15].

Estos controles te dejan modificar:

• La propiedad primary en true o false.
• El label o texto del botón, por ejemplo cambiarlo a Click me.
• El background color mediante un selector visual.
• El tamaño con opciones como small o medium.
• El evento onClick, vinculado a los actions de Storybook.

Si trabajaste con Figma en un design system, vas a reconocer este patrón: lo que en Figma llamamos variantes, aquí se traduce en controls manipulables vía código.

¿Para qué sirven los controls en Storybook? Permiten probar un componente con distintas propiedades sin tocar el código fuente, validando rápidamente cómo responde a diferentes estados, tamaños o textos.

¿Cómo funciona la fuente de verdad de un design system?

Storybook actúa como single source of truth para tu equipo. Cuando un desarrollador necesita un botón con ciertas características, entra a la documentación, revisa si existe el componente y obtiene el código listo para usar con la opción Show code [07:00].

La idea clave es que el desarrollador no tenga que copiar clases manualmente. En frameworks modernos, el componente debe recibir props como size con un valor, automatizando el uso y reduciendo errores.

¿Qué archivos genera Storybook en tu proyecto?

Al abrir el folder del proyecto, encuentras una estructura organizada que conviene conocer antes de personalizar nada. Cada carpeta tiene un rol específico dentro del flujo de trabajo.

Los elementos principales son:

• Carpeta .storybook: contiene main.js, donde se configuran las rutas de las historias y los addons esenciales como accesibilidad.
• Archivo preview.js: define configuraciones de previsualización, actions y controllers.
• node_modules: aloja todas las librerías instaladas, no se sube a GitHub por su peso.
• Carpeta stories: incluye los componentes de ejemplo con sus assets, estilos y archivos de historias.

Dentro de stories vas a ver imágenes en la carpeta de assets, como el logo del header, junto con los componentes que Storybook crea por defecto [10:30].

¿Cuáles son los tres archivos principales de un componente?

Cada componente en Storybook se construye con tres archivos que separan responsabilidades de forma clara:

1. Archivo JavaScript (button.js): aquí accedes al DOM, creas el elemento HTML del botón y le asignas las clases necesarias. Es el responsable de la funcionalidad.
2. Archivo CSS (button.css): define los estilos basados en las clases declaradas en el JavaScript. Solo escribes CSS puro.
3. Archivo stories (button.stories.js): importa el componente y define las historias que Storybook va a renderizar en el navegador.

Estos tres archivos trabajan juntos: la lógica vive en JavaScript, los estilos en CSS y la visualización se materializa gracias al archivo de historias [12:45].

¿Qué herramientas extra ofrece la barra superior de Storybook?

La barra superior incluye funcionalidades adicionales para inspeccionar tus componentes en distintos contextos. Puedes revisar el padding, medir elementos, simular vistas en mobile o desktop y validar comportamientos responsivos.

Estas herramientas se exploran a fondo más adelante con los addons, pero desde el inicio te dan una idea del poder que tiene Storybook para validar componentes antes de integrarlos en producción.

Con la instalación lista y la estructura comprendida, el siguiente paso es organizar la arquitectura y definir convenciones de nombramiento para que tus componentes escalen sin caos. ¿Qué patrón de organización usas tú en tus proyectos? Cuéntamelo en los comentarios.