Arquitectura de componentes en Storybook con Atomic Design

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:007:05

Arquitectura de componentes en Storybook con Atomic Design

Curso de Storybook: Sistemas de Diseño con JavaScript

Clase 4 de 21

Clase 4 / 21

Recursos

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:

Revisar la arquitectura del componente en Figma e identificar a qué nivel pertenece.
Definir el title siguiendo el patrón DesignSystem/Categoría/Componente.
Mantener el inglés como idioma base para los niveles, sobre todo si el equipo es internacional.
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.

Resumen

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

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', };

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?

¿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.

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

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?

Los pasos concretos son:

Revisar la arquitectura del componente en Figma e identificar a qué nivel pertenece.
Definir el title siguiendo el patrón DesignSystem/Categoría/Componente.
Mantener el inglés como idioma base para los niveles, sobre todo si el equipo es internacional.
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.

Comentarios (4)4 comentarios

Dennys Reyes

Hace 4 años

acá el código. 🤓

import ___ from './button';

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

Leobardo Licona Soto

Hace 3 años

¡Excelente! Me llama la atención que se está llevando el curso en Vanillajs. Estaría bueno crear los componentes con la metodología de los "Web Components", existe un curso de Platzi donde enseñan esto. https://platzi.com/cursos/web-components-javascript/ Gracias por estos cursos tan geniales.

Daniel Lucumi

Hace 2 años

He usado storybook por 2 años y creo que es una excelente herramienta, podemos tener una visual de nuestros componentes asi la aplicacion o sitio web no este construido en su totalidad

Irving Juárez

Vale la pena ponerle Design System a la carpeta de Story book? Tomando en cuenta que la herramiento ya es un Design System?

Francisco Javier Araujo de la Garza

Hace 3 meses•editado

Cada quien decide el nombre que le pone, yo lo omitiría

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

Arquitectura de componentes en Storybook con Atomic Design

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