Organizar tu Storybook desde cero requiere dos pilares: una arquitectura de componentes clara y una convención de nombres consistente. Aquí verás cómo aplicar Atomic Design a tu primer componente button para que tu librería se lea ordenada, escalable y lista para crecer.

¿Cómo preparar la estructura de carpetas para un componente en Storybook?

Antes de escribir una sola línea de código, conviene limpiar lo que Storybook genera por defecto y empezar con una base propia. En el minuto [00:30] se borran los archivos de ejemplo para arrancar desde cero con tu propia convención.

Para el componente button necesitas tres archivos dentro de una carpeta con el mismo nombre:

• button.js: contiene la lógica del componente en JavaScript.
• button.css: define los estilos.
• button.stories.js: declara las historias que Storybook leerá.

El sufijo .stories.js no es opcional. Storybook detecta esa palabra clave dentro del archivo de configuración principal para identificar qué archivos debe mostrar como historias en la interfaz.

¿Por qué el archivo debe llamarse button.stories.js? Porque Storybook escanea el proyecto buscando archivos que contengan stories en su nombre. Sin ese patrón, tu componente no aparece en la interfaz.

¿Cómo escribir la primera historia y conectar el componente?

Dentro de button.stories.js empiezas importando el componente y exportando un objeto por defecto. Ese objeto le dice a Storybook qué mostrar y cómo nombrarlo.

La estructura inicial luce así:

js import Name from './button';

export default { title: 'Design System/Atoms/Button', };

La propiedad title es la pieza más importante en este punto. No se llama name, se llama title, y funciona como una ruta jerárquica. Cada barra / representa un nivel dentro del árbol de navegación de Storybook, exactamente como si estuvieras creando carpetas anidadas.

En el minuto [04:30] se explica que esta ruta replica la arquitectura definida en Figma desde el curso de design system, donde cada componente tenía sus variantes documentadas.

¿Qué es Atomic Design y cómo se aplica al naming?

Atomic Design es una metodología que clasifica los componentes según su nivel de complejidad: átomos, moléculas, organismos y niveles superiores. Los átomos son los bloques más pequeños e indivisibles, como un button, un input o un label. Las moléculas combinan átomos, y los organismos combinan moléculas.

¿Qué es un átomo en Atomic Design? Es el componente más pequeño y reutilizable de tu sistema, como un botón o un campo de texto. No se puede descomponer en piezas funcionales más simples.

Al traducir esta jerarquía al title de Storybook obtienes una ruta legible:

• Design System como contenedor raíz de toda la librería.
• Atoms como agrupador de los componentes más básicos.
• Button como el componente específico.

Usar el plural Atoms permite que, cuando agregues más átomos como Input o Checkbox, todos se agrupen automáticamente bajo la misma rama. Si dejas Atom en singular, cada componente podría quedar suelto sin agrupación visual clara.

¿Por qué importa el naming en un design system?

Un naming consistente convierte tu Storybook en documentación viva. Cualquier persona del equipo, ya sea diseño o desarrollo, encuentra el componente sin preguntar. Además, cuando el naming refleja la arquitectura de Figma, eliminas la fricción entre lo que diseño entrega y lo que desarrollo construye.

En el minuto [06:00] se enfatiza que esta convención no es decorativa: define cómo se estructura tu design system tanto en el lado de diseño como en el de código.

¿Cómo se traduce la arquitectura de Figma al código?

En Figma, cada componente del design system tiene su propia arquitectura con variantes documentadas. Esa misma jerarquía se replica en el title del archivo de stories. La idea es que la fuente de verdad del diseño y la fuente de verdad del código hablen el mismo idioma.

Los pasos concretos son:

1. Revisar la arquitectura del componente en Figma e identificar a qué nivel pertenece.
2. Definir el title siguiendo el patrón DesignSystem/Categoría/Componente.
3. Mantener el inglés como idioma base para los niveles, sobre todo si el equipo es internacional.
4. Usar plurales en los agrupadores (Atoms, Molecules) para escalar sin reorganizar.

Con esto, cuando Storybook lea el archivo, mostrará el componente perfectamente anidado dentro de la jerarquía esperada, listo para recibir variantes y estados en las siguientes iteraciones.

El siguiente paso natural es la tokenización: cómo trasladar los valores del design system a variables de CSS reutilizables. ¿Ya tienes definidos tus tokens de color y espaciado, o vas a empezar desde cero? Cuéntame en los comentarios.