Atomic Design: Arquitectura de Componentes

Todo equipo frontend enfrenta eventualmente el mismo problema: los componentes se multiplican, las convenciones de nombres se diluyen, y lo que comenzó como un código limpio se convierte en un mosaico de soluciones únicas. Atomic Design resuelve esto dando a tu arquitectura de componentes una estructura clara y repetible, inspirada en la química. En lugar de adivinar dónde pertenece un nuevo componente, sigues una jerarquía que escala desde un simple botón hasta una aplicación completa.

Qué es Atomic Design?

Brad Frost introdujo Atomic Design en 2013 como un modelo mental para construir interfaces de usuario. La idea central es simple: así como la materia en la naturaleza está compuesta por átomos que se combinan en moléculas y luego en organismos complejos, las interfaces de usuario pueden descomponerse en cinco niveles jerárquicos.

Los cinco niveles son Átomos, Moléculas, Organismos, Templates y Páginas. Cada nivel se construye sobre el anterior. La regla crítica: las dependencias solo fluyen hacia abajo — los átomos no importan nada, las moléculas importan solo átomos, los organismos importan moleculas, y así sucesivamente. Esta única restricción elimina las dependencias circulares y hace que cada componente sea predecible.

Los cinco niveles de un vistazo

Los cinco niveles explicados

Nivel 1: Atomos

Los elementos UI más pequeños con significado. Botones, inputs, labels, encabezados, iconos, badges, imágenes y enlaces. No pueden descomponerse más sin perder su propósito. Piensa en ellos como la tabla periódica de tu sistema de diseño. Los átomos son autónomos — reciben todos los datos via props y se estilan con design tokens.

Nivel 2: Moleculas

Pequeños grupos de átomos que trabajan juntos como unidad funcional. Una SearchBar (Input + Button), un FormField (Label + Input + Error), un NavLink (Link + Icon), una Card (Imagen + Encabezado + Texto). La prueba clave: este grupo sirve a un propósito único y claro? Si es así, es una molécula.

Nivel 3: Organismos

Secciones complejas y autónomas de una página. Un Header (Logo + Nav + SearchBar + Selector de Idioma), una sección Hero, un Footer, un formulario de contacto, una BlogSidebar, una tabla de precios. Los organismos son el primer nivel que se siente como una verdadera "sección" de un sitio web. Gestionan el layout y la coordinación de sus hijos.

Nivel 4: Templates y Páginas

Los templates definen la estructura de la página — donde van los organismos y cómo fluye el layout. En Astro, los templates corresponden a archivos de layout (BaseLayout, BlogLayout). Las páginas son templates llenos de contenido real — los archivos de ruta en src/pages/ que los usuarios ven. Las páginas manejan la obtención de datos y los pasan a layouts y organismos.

Atomic Design vs. arquitectura tradicional

Átomos en la práctica

Los átomos deben ser autónomos. Reciben todos los datos a través de props y nunca obtienen datos ni importan otros componentes. Se estilan usando design tokens (CSS custom properties), nunca valores hardcodeados.

---
interface Props {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
}
const { variant = 'primary', size = 'md', disabled = false } = Astro.props;
---
<button
  class:list={['btn', `btn--${variant}`, `btn--${size}`]}
  disabled={disabled}
>
  <slot />
</button>

---
interface Props {
  type?: 'text' | 'email' | 'search' | 'password';
  name: string;
  placeholder?: string;
  required?: boolean;
}
const { type = 'text', name, placeholder, required = false } = Astro.props;
---
<input
  type={type}
  name={name}
  placeholder={placeholder}
  required={required}
  class="input"
/>

---
interface Props {
  level?: 1 | 2 | 3 | 4 | 5 | 6;
  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl';
}
const { level = 2, size = 'lg' } = Astro.props;
const Tag = `h${level}`;
---
<Tag class:list={['heading', `heading--${size}`]}>
  <slot />
</Tag>

Moleculas: El pegamento funcional

Las moléculas combinan dos o más átomos en una unidad funcional. La distinción clave: una molécula hace algo que sus átomos individuales no pueden hacer solos.

La prueba de la molécula

Pregúntate: “Este grupo de átomos sirve a un propósito único y claro?” Si la respuesta es si, es una molécula. Si sirve a multiples propósitos o contiene otras moléculas, probablemente sea un organismo.

Organismos: Secciones reales de página

Los organismos son el primer nivel que se siente como una “sección” de una página. Son componentes complejos y autónomos hechos de moléculas y átomos.

Estructura de carpetas en Astro

src/
├── components/
│   ├── atoms/        → Button, Input, Heading, Icon, Badge, Image, Link
│   ├── molecules/    → SearchBar, FormField, NavLink, Card, Breadcrumbs
│   ├── organisms/    → Header, Footer, Hero, ContactForm, BlogSidebar
│   └── seo/          → SEO.astro, Componentes de Schema
├── layouts/          → BaseLayout, BlogLayout (= Templates)
├── pages/            → index.astro, blog/[slug].astro (= Paginas)
├── styles/
│   ├── global.css
│   └── tokens/       → colors.css, typography.css, spacing.css
├── lib/              → utils.ts, constants.ts
└── types/            → Definiciones TypeScript

La regla de oro

Cada atomo necesita: interfaces de props adecuadas, markup accesible, cobertura completa de estados (hover, focus, active, disabled, error) e integracion con design tokens. Un átomo mal diseñado propaga sus problemas por todas partes.

Evolucion de un proyecto

Preguntas frecuentes

Por que Atomic Design gana

Después de aplicar Atomic Design en más de 30 proyectos en producción, estos son los beneficios que emergen consistentemente. Si quieres ver cómo se implementa en la práctica con más de 45 componentes reales, consulta el artículo Atomic Design en la práctica.