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.