En este tutorial vamos a ver paso a paso, como implementar el sistema de diseño Atomic Design en Drupal usando Storybook y Single Directory Components.

Vamos a ver como podemos separar casi a un 100% la implementacion del diseño (estructuras y estilos) creando un theme custom para desarrollar nuestros componentes que nos permitan implementar todo lo que requiera el diseño propuesto que puede venir en un modelado en figma o bien simplemente ser una creación mas improvisada (copiar buenas ideas de otras webs).

Pero primero, ¿que es atomic design?

Atomic Design es una metodología para crear sistemas de diseño escalables, propuesta por Brad Frost. Se basa en la idea de construir interfaces a partir de componentes pequeños y reutilizables, siguiendo una jerarquía de cinco niveles: átomos, moléculas, organismos, templates y pages. Cada nivel representa una mayor complejidad y contexto de uso.
Conviene usar Atomic Design cuando se desarrollan productos digitales grandes o mantenibles a largo plazo, especialmente con equipos multidisciplinarios que necesitan consistencia visual y funcional.

Pros:

1. Fomenta la reutilización de componentes.
2. Mejora la consistencia visual del sistema.
3. Facilita el trabajo en equipo y la colaboración.
4. Acelera el desarrollo de interfaces.
5. Permite testear partes pequeñas de la UI de forma aislada.

Contras:

1. Puede ser complejo de implementar al inicio.
2. Requiere disciplina para mantener la estructura.
3. No siempre encaja con flujos de trabajo tradicionales.
4. Puede generar sobrecarga en proyectos simples.
5. La nomenclatura puede no ser intuitiva para todos.

En que casos nos conviene usar este enfoque para proyectos Drupalizados?

• El cliente necesita ver rapidamente algo construido y la estructura aún no esta ni planificada.
• El proyecto requiere de una migracion de datos y necesitamos ir en paralelo con la construccion del sitio.
• Necesitamos que el equipo se mantenga activo y avanzando en el proyecto, por lo que podemos avanzar los frontends con el maquetado y los programadores backend por otro.
• Tenemos varios maquetadores en el equipo y se requiere un trabajo bien organizado (con este enfoque se pueden dividir componentes, moleculas y organismos).

¿Cómo implementamos todo esto en un proyecto Drupal?

Vamos a usar las siguientes herramientas:

• DDEV para el entrono local de desarrollo.
• Storybook para validar nuestros componentes.
• Custom theming (Creación de tema custom).
• Single Directory Components (Creación de componentes).

Damos por descontado que ya tenemos un Drupal 11 instalado y preparado para trabajar en modo desarrollo. Acá dejo un tutorial paso a paso de como montar un Drupal 11 usando DDEV.

Creando el theme personalizado

Comenzamos creando y activando el custom theme, ejecutando el siguiente comando crearemos dentro de la carpeta web/themes/custom/ nuestro theme o tema con el nombre que deseemos, en este caso iobase.

Nota: ejecutamos este comando desde la raiz del proyecto

ddev php web/core/scripts/drupal generate-theme iobase --path themes/custom

Resultado

Ahora que tenemos creado el tema custom vamos a instalarlo y activarlo para comenzar a usarlo como tema para los visitantes del sitio en modo anonimo (para admin seguimos usando el tema por defecto que es claro, luego podemos cambiarlo si queremos también).

ddev drush theme:enable iobase
ddev drush config-set system.theme default iobase

Si visitamos el sitio ahora en modo incognito veremos que el tema ahora ya no tiene estilos, lo cual es logico porque nuestro theme custom esta recien creado y con todo lo basico por defecto.

Configurando Storybook en DDEV

Primero veamos brevemente que es storybook y como puede ayudarnos en el proceso de implementar Atomic Design en nuestro proyecto.

Storybook es una herramienta de desarrollo frontend que permite construir y visualizar componentes de UI de forma aislada, fuera de la aplicación principal. Es ideal para desarrollar, testear y documentar componentes de manera independiente. En el contexto de un sistema de diseño basado en Atomic Design, Storybook es clave porque permite ver y probar átomos, moléculas y organismos por separado, asegurando que cada pieza funciona correctamente antes de integrarse.

Cómo ayuda con Atomic Design:

• Permite documentar visualmente cada nivel del sistema.
• Facilita la colaboración entre diseñadores y desarrolladores.
• Acelera el testing de componentes reutilizables.
• Reduce errores de integración.
• Mejora la comunicación del diseño al mantener un catálogo vivo y navegable.

Bien para poder usar storybook en nuestro proyecto necesitamos configurar ddev para que nos genere una instancia de storybook y asi podamos usarlo de manera local

Vamos al paso a paso, primero instalamos el modulo contrib storybook y luego lo configuraremos  

ddev composer require 'drupal/storybook:^1.0'
ddev drush en -y storybook

Ahora vamos a configurar los permisos que este modulo requiere parar que se pueda acceder a los componentes: /admin/people/permissions

La documentación oficial dice lo siguiente: Asegúrate de otorgar permiso para renderizar historias de Storybook a usuarios anónimos. Mantén este permiso deshabilitado en producción.

Ahora tenemos que agregar configuración en el archivo development.services.yml para que la comunicación entre drupal y storybook funcione correctamente

Editamos el archivo development.services.yml

parameters:
  http.response.debug_cacheability_headers: true
  # Remember to disable development mode in production!
  storybook.development: true
  cors.config:
    enabled: true
    allowedHeaders: [ '*' ]
    allowedMethods: [ '*' ]
    allowedOrigins: [ '*' ]
    exposedHeaders: false
    maxAge: false
    supportsCredentials: true
  twig.config:
    debug: true
    auto_reload: true
    cache: false
services:
  cache.backend.null:
    class: Drupal\Core\Cache\NullBackendFactory

Guardamos y limpiamos caches

ddev drush cr

Es importante tener activado el modo de desarrollo local en drupal, dejo aqui todo lo necesario para hacerlo.

Por el lado de drupal eso seria todo por ahora, lo que necesitamos hacer ahora es decirle a DDEV que vamos a usar storybook, para eso editamos el file: .ddev/config.yaml

donde indica la imagen anterior colocamos lo siguiente:

#########################################################################
# Begin DDEV for Storybook Customizations
#########################################################################
nodejs_version: "18"
webimage_extra_packages:
  - pkg-config
  - libpixman-1-dev
  - libcairo2-dev
  - libpango1.0-dev
  - make
web_extra_exposed_ports:
  - name: storybook
    container_port: 6006
    http_port: 6007
    https_port: 6006
web_extra_daemons:
  - name: node.js
    command: "tail -F package.json > /dev/null"
    directory: /var/www/html
hooks:
  post-start:
    - exec: echo '============================================================================'
    - exec: echo '                                  NOTICE'
    - exec: echo '============================================================================'
    - exec: echo 'The node.js container is ready. You can start storybook by typing:'
    - exec: echo 'ddev yarn storybook'
    - exec: echo
    - exec: echo 'By default it will be available at https://change.me.ddev.site:6006'
    - exec: echo "Use ddev describe to confirm if this doesn't work."
    - exec: echo 'Check the status of startup by running "ddev logs --follow --time"'
    - exec: echo '============================================================================'

#########################################################################
# End DDEV for Storybook Customizations
#########################################################################

Guardamos y reiniciamos los contendores, es decir ddev 

ddev restart

Luego de tener todo nuevamente levantado vamos a la raiz del proyecto e instalamos lo siguiente, cuando nos pregunte: Do you want to manually choose a Storybook project type to install? contestamos Yes y seleccionamos la opcion Server

ddev exec npx storybook@latest init

Luego de que finalice la instalación tendremos estos nuevos archivos en nuestro proyecto

Editamos el file: package.json y cambiamos la linea

"storybook": "storybook dev -p 6006",

por esta otra y guardamos

"storybook": "storybook dev -p 6006 --no-open",

Ahora ya podemos ejecutar el comando para correr nuestro Storybook

ddev npm run storybook

Si todo fue bien deberíamos ser capaces de entrar usando el navegador para saber en que direccion esta corriendo ejecutamos 

ddev describe

Vamos al navegador a ver los resultados

Ya casi estamos, vamos a hacer las ultimas configuraciones para que todo quede bien.

Vamos a editar el file: .storybook/main.js tiene que quedar de la siguiente manera:

/** @type { import('@storybook/server-webpack5').StorybookConfig } */
const config = {
  stories: [
    "../web/**/*.mdx",
    "../web/**/*.stories.@(json|yaml|yml)"
  ],
  staticDirs: ['../images'],
  addons: [
    "@storybook/addon-webpack5-compiler-swc",
    "@storybook/addon-essentials",
    "@chromatic-com/storybook"
  ],
  framework: {
    name: "@storybook/server-webpack5",
    options: {}
  }
};
export default config;

Y en la raiz del proyecto creamos la carpeta images donde pondremos imagenes de testing que usaremos en storybook, mas adelante veremos como en un ejemplo práctico.

Con esto ya estamos listos para usar Storybook sin problemas, como veremos mas adelante cada vez que agreguemos o actualicemos componentes (SDC) tendremos que ejecutar el siguiente comando para que Storybook se entere de los cambios: dv drush storybook:generate-all-stories

Ahora si a crear componentes se ha dicho !!!

Creando nuestro primer componente

Bien ya tenemos todo listo, vamos a crear un componente muy básico que seguramente todo proyecto web tiene como es el famoso boton o link denominado CTA (por sus siglas en inglés Call To Action). Si bien es discutible creo que todos estaremos de acuerdo en que es un componente atómico, es decir un átomo para el sistema de diseño Atomic Design. Por lo que lo categorizaremos dentro de la carpeta atoms.

Creamos nuestro componente SDC usando drush

ddev drush gen sdc

El genrador nos hará preguntas al respecto del componente que queremos crear, en nuestro caso el CTA component podría ser algo como lo siguiente: (prestar atención que la primer pregunta es acerca de en que tema queremos crear nuestro componente, en nuestro ejemplo el theme se llama iobase):

El componente se crea y se aloja en la carpeta components dentro de nuestro theme iobase. Para mejor organizacion yo suelo crear la siguiente estructura de carpetas de componentes (respetando el atomic design pattern):

por lo que el componente CTA que acabamos de crear lo muevo dentro de la carpeta atoms manualmente.

Es necesario crear el file cta.stories.twig para que se pueda compilar y asi generar el cta.stories.json que es el file que interpreta Storybook

Ahora vamos a exportar el componente para que lo pueda interpretar Storybook

ddev drush storybook:generate-all-stories

Es importante destacar que este post fue inspirado en un video de youtube proporcionado de manera muy generosa por parte de la empresa Drupak así que vaya mi agradecimiento y mención para este increíble grupo de drupaleros.