Comprender la forma correcta de escribir historias en Storybook es fundamental para construir un design system sólido y reutilizable. La sintaxis se basa en un formato específico que permite representar componentes con diferentes variantes, argumentos y parámetros, todo orientado a visualizar y probar escenarios de forma eficiente.
¿Qué formato se utiliza para escribir historias en Storybook?
La estructura que propone la documentación oficial de Storybook se apoya en los ECMAScript modules [01:10]. Esto significa que cada historia utiliza la sintaxis de export default seguida de un objeto con la configuración del componente. Este formato estandarizado es la base sobre la cual se construyen todas las historias.
Dentro de este objeto podemos definir propiedades como el title, que permite renombrar las historias y organizar la jerarquía de componentes en el panel lateral de Storybook [02:30]. El nombre que asignemos aquí será el que aparezca visible cuando exploremos nuestras historias en el navegador.
Una decisión importante de arquitectura es separar los archivos: un archivo JavaScript para el componente y otro para la historia [01:46]. Aunque la documentación muestra ejemplos donde todo convive en un solo archivo, mantener la separación facilita el mantenimiento a largo plazo.
¿Cómo se definen variantes de un componente?
Cuando un componente tiene múltiples variantes — como primary, secondary o tertiary — se pueden exportar individualmente dentro del mismo archivo de historia [03:15]. Cada variante recibe sus propios parámetros, como size o style, que determinan cómo se pintará el componente.
Sin embargo, existe otro enfoque igualmente válido: en lugar de crear variantes fijas, podemos aprovechar los controladores de Storybook [03:40]. Estos controles permiten modificar atributos en tiempo real desde la interfaz:
- Cambiar el estilo a outlined directamente desde el panel de controles.
- Ajustar tamaños sin necesidad de crear una historia separada.
- Probar combinaciones que no estaban predefinidas.
Esta estrategia reduce la cantidad de variantes escritas y da mayor flexibilidad al momento de explorar el componente.
¿Por qué son importantes los argumentos, parámetros y decoradores?
Estos tres elementos trabajan juntos para cubrir la mayor cantidad de escenarios posibles en los que un componente podría utilizarse [05:50].
¿Qué papel juegan los argumentos?
Los argumentos (args) permiten cambiar los atributos que recibe un componente [04:32]. Por ejemplo, si un botón acepta propiedades como tamaño o color, los argumentos son los valores que le enviamos para que se renderice de cierta forma. Se profundiza en ellos junto con los tipos de argumentos en la configuración avanzada de cada historia.
¿Para qué sirven los parámetros?
Los parámetros (parameters) modifican aspectos más específicos de la visualización [05:16]. Un ejemplo clásico es definir colores de fondo: indicarle a Storybook que el fondo puede ser rojo, verde o azul para verificar cómo se comporta el componente en diferentes contextos visuales.
¿Qué aportan los decoradores?
Los decoradores (decorators) envuelven el componente con funcionalidad o estructura adicional [07:02]. Son especialmente útiles cuando necesitamos simular un contexto particular, como un tema dark o un contenedor con ciertas dimensiones.
La mentalidad clave aquí es pensar en reutilización [06:05]. Cuando construimos componentes para un design system, no basta con que funcionen en una sola pantalla. Hay que validar múltiples escenarios:
- Fondos claros y oscuros.
- Diferentes tamaños de pantalla.
- Componentes anidados dentro de otros componentes.
¿Cómo manejar historias con múltiples componentes?
Storybook también permite trabajar con componentes compuestos [07:30]. Un caso típico es una lista que contiene ítems como hijos. En este escenario se importan ambos componentes y se define cómo se relacionan dentro de la historia, indicando qué elementos hijos debe renderizar — es decir, pintar o hacer visibles en el navegador.
Este patrón es común en design systems donde los componentes no viven aislados, sino que interactúan entre sí formando estructuras más complejas.
La documentación oficial de Storybook también menciona la play function [05:02], una funcionalidad que permite simular interacciones del usuario directamente en las historias. Además, si dominas HTML y quieres contribuir al open source, la documentación carece de ejemplos con HTML puro y de traducciones al español [02:08], lo cual representa una excelente oportunidad para hacer contribuciones significativas.
¿Ya empezaste a escribir tus propias historias? Comparte en los comentarios qué escenarios te han resultado más desafiantes de configurar.
