Cómo estructurar historias en Storybook

Curso de Storybook: Sistemas de Diseño con JavaScript

Contenido del curso

Visión general de los sistemas de diseño en desarrollo

Desarrollo de componentes

Historias en Storybook

Essential Addons en Storybook

Pruebas de componentes en Storybook

Próximos pasos

21
Qué sigue después de Storybook
01:17 min

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:009:41

Cómo estructurar historias en Storybook

Curso de Storybook: Sistemas de Diseño con JavaScript

Clase 11 de 21

Clase 11 / 21

Recursos

Si estás armando un design system y quieres que tus componentes vivan dentro de Storybook, necesitas dominar la forma en que se escriben las historias. Aquí te explico cómo estructurar ese formato basado en ECMAScript Modules, qué papel juegan los argumentos, parámetros y decoradores, y por qué importa pensar en escenarios cuando construyes componentes reutilizables.

¿Qué formato usa Storybook para escribir historias?

La documentación oficial de Storybook define una estructura concreta para representar componentes. Esa estructura se apoya en ECMAScript Modules, la sintaxis moderna de JavaScript que usa export default seguido de llaves para exponer la configuración de la historia.

Dentro de ese bloque defines el componente, su título y los datos que Storybook necesita para mostrarlo. Es la misma forma que ya viste en clases anteriores, pero ahora con un detalle: en la documentación oficial, el componente y la historia van en un mismo archivo para facilitar la lectura. En tu proyecto los separamos a propósito en un archivo de JavaScript y otro para la historia, así mantienes el código más limpio.

¿Qué son los ECMAScript Modules en Storybook? Es la sintaxis estándar de JavaScript para exportar e importar módulos. En Storybook se usa con export default para definir la configuración base de cada historia.

¿Cómo renombrar una historia con title?

Para cambiar el nombre con que aparece tu componente en el panel de Storybook, usas la propiedad title dentro del export default. Ese título es lo que Storybook lee y luego muestra en su interfaz.

Si escribes title: 'Primary', eso es lo que verás en el árbol lateral. Y si tu componente tiene varias variantes, puedes nombrarlas como primary, secondary o tertiary, y cada una aparecerá como una opción aparte al hacer clic.

¿Variantes fijas o controles dinámicos en Storybook?

Aquí hay una decisión de diseño interesante. Puedes definir cada variante de tu botón como una historia separada (uno default, otro primary, otro outlined) o puedes dejar una sola historia y manipular sus propiedades desde los controles dinámicos de Storybook.

En este curso elegí la segunda ruta. ¿Por qué? Porque los controles te permiten cambiar size, style u otros atributos sin necesidad de duplicar historias. Si necesitas un botón outlined, lo seleccionas en el panel de controles y listo.

Variantes fijas: útiles cuando quieres que cada estilo aparezca documentado por separado.
Controles dinámicos: útiles cuando prefieres una historia flexible que se adapte a múltiples casos.
Combinación de ambos: lo más común en design systems maduros.

Esa flexibilidad es justo lo que hace que Storybook se sienta como una herramienta viva.

¿Qué hacen los argumentos en una historia?

Los argumentos son los valores que le pasas al componente para que se pinte de cierta forma. Si tu botón pide un size y un style, esos son los argumentos que defines en la historia. En la siguiente clase los vemos a fondo, pero por ahora quédate con la idea: argumentos = los datos concretos que tu componente recibe.

¿Cómo afectan parámetros y decoradores la visualización?

Los parámetros son configuraciones específicas que modifican los controladores y el entorno visual de la historia. Por ejemplo, puedes definir un parámetro backgrounds con valores como red, green o blue, y Storybook te dejará cambiar el fondo del canvas desde la interfaz.

Los decoradores, por su parte, envuelven tu componente con contexto adicional. Sirven cuando necesitas que tu historia se renderice dentro de un contenedor, un theme provider o cualquier capa visual extra.

¿Para qué sirven los parámetros en Storybook? Para configurar opciones específicas de cada historia, como fondos, viewports o controles personalizados, sin tocar el componente original.

¿Por qué pensar en escenarios al construir un design system?

Cuando desarrollas un componente para una sola pantalla, casi nunca revisas todos los escenarios posibles. Pero en un design system el componente se reutiliza en muchos contextos: tema oscuro, tema claro, pantallas pequeñas, fondos con color, listas anidadas.

Ahí es donde argumentos, parámetros y decoradores se vuelven tus aliados. Te permiten validar que el botón funcione en X cantidad de escenarios antes de soltarlo al equipo. Y cuando el diseñador te diga “esto tiene que verse bien en dark mode”, ya sabes que la documentación de Storybook tiene una forma de probarlo.

¿Se pueden combinar varios componentes en una historia?

Sí. Storybook soporta historias con más de un componente, lo cual es útil cuando trabajas con relaciones padre-hijo. El ejemplo clásico es una lista con sus ítems: importas ambos componentes, defines cómo se renderizan juntos y dejas que la historia muestre la composición completa.

Renderizar, en este contexto, significa pintar el componente en el navegador para que sea visible. Así puedes ver cómo se comporta una lista con uno, tres o diez ítems sin escribir código adicional cada vez.

Importas el componente padre y el componente hijo.
Defines la estructura jerárquica dentro de la historia.
Renderizas los hijos como parte del padre.

Con eso ya tienes una base sólida para escribir historias en Storybook usando la sintaxis de ECMAScript Modules y aprovechar argumentos, parámetros y decoradores para cubrir cada escenario que tu design system necesite. ¿Te animas a contribuir con un ejemplo en HTML a la documentación oficial? Cuéntame en los comentarios.

Resumen

¿Qué formato usa Storybook para escribir historias?

¿Qué son los ECMAScript Modules en Storybook? Es la sintaxis estándar de JavaScript para exportar e importar módulos. En Storybook se usa con export default para definir la configuración base de cada historia.

¿Cómo renombrar una historia con title?

¿Variantes fijas o controles dinámicos en Storybook?

Variantes fijas: útiles cuando quieres que cada estilo aparezca documentado por separado.
Controles dinámicos: útiles cuando prefieres una historia flexible que se adapte a múltiples casos.
Combinación de ambos: lo más común en design systems maduros.

Esa flexibilidad es justo lo que hace que Storybook se sienta como una herramienta viva.

¿Qué hacen los argumentos en una historia?

¿Cómo afectan parámetros y decoradores la visualización?

¿Para qué sirven los parámetros en Storybook? Para configurar opciones específicas de cada historia, como fondos, viewports o controles personalizados, sin tocar el componente original.

¿Por qué pensar en escenarios al construir un design system?

¿Se pueden combinar varios componentes en una historia?

Importas el componente padre y el componente hijo.
Defines la estructura jerárquica dentro de la historia.
Renderizas los hijos como parte del padre.

Visión general de los sistemas de diseño en desarrollo

Qué es Storybook y para qué sirve

Creación de Sistemas de Diseño con Storybook

Desarrollo de componentes

Instalación de Storybook con Vanilla JavaScript

Arquitectura de componentes en Storybook con Atomic Design

Exportar design tokens de Figma a CSS

Crear un botón reutilizable con Storybook

Estilización de Botones en CSS: Clases y Hover Interactivo

Componente Card en JavaScript con BEM

Container Queries vs Media Queries en CSS

Estilización de Componentes CSS con Container Queries

Historias en Storybook

Cómo estructurar historias en Storybook

Controles de argTypes para botones en Storybook

Parámetros y decoradores en Storybook

Essential Addons en Storybook

Qué son los add-ons en Storybook

Actions y Backgrounds en Storybook

Viewports y outline en Storybook

Pruebas de componentes en Storybook

Cómo usar el test runner de Storybook

Pruebas de Interacción con Storybook y Testing Library

Pruebas de Accesibilidad en Storybook con Add-ons

Pruebas visuales de UI con Chromatic

Próximos pasos

Qué sigue después de Storybook

Cómo estructurar historias en Storybook

Progreso del curso

Visión general de los sistemas de diseño en desarrollo

Desarrollo de componentes

Historias en Storybook

Essential Addons en Storybook

Pruebas de componentes en Storybook

Próximos pasos

Recursos

Recursos