🖼️ 3.6 · UI/UX avanzado: Atomic Design y design systems en React

🎯 Objetivo del tema

🗺️ Mapa del tema

Cuando tu app crece de 5 componentes a 50, surge un problema: el Button de la pantalla de login se ve diferente al de la pantalla de perfil, y nadie sabe por qué. El Atomic Design (de Brad Frost) resuelve esto con una jerarquía clara: átomos (Button, Input, Label) → moléculas (SearchBar = Input + Button) → organismos (Header con logo + nav + search) → templates (layout principal) → páginas (instancias concretas). Es la metodología que usan Linear, Notion, Figma, y los designers profesionales. Hoy la aplicas a tu app de Atlas Mundial.

3.6.1 Atomic Design: la metodología que escaló React

Brad Frost publicó Atomic Design en 2013 inspirado en la química: así como la materia se compone de átomos, las interfaces se componen de 5 niveles de componentes. Es la metodología estándar en design systems profesionales: Linear, Notion, Figma, IBM, Salesforce. Te da un vocabulario común y una jerarquía clara que escala de 5 a 5000 componentes sin perder consistencia.

3.6.2 Átomos: Button, Input, Label, Badge, Spinner

Los átomos son los componentes MÁS PEQUEÑOS de tu app. No tienen estado propio (no son useState), no hacen fetch, no tienen lógica. Son BLOQUES VISUALES puros: Button, Input, Label, Badge, Spinner, Avatar, Icon. Son la base de todo lo demás, así que deben estar bien hechos y ser REUTILIZABLES. Un Button con 10 props para 10 variantes es un átomo bien diseñado.

El átomo Button con 4 variantes y 3 tamaños

// atoms/Button.jsx: el átomo más importante de tu app
import './Button.css';

// Props del Button: variant, size, disabled, loading, onClick, children
export function Button({
  variant = 'primary',     // primary | secondary | danger | ghost
  size = 'md',           // sm | md | lg
  disabled = false,
  loading = false,
  onClick,
  type = 'button',
  children,
  ...rest
}) {
  return (
    <button
      type={type}
      onClick={onClick}
      disabled={disabled || loading}
      className={`btn btn-${variant} btn-${size} ${loading ? 'btn-loading' : ''}`}
      {...rest}
    >
      {loading ? <span className="spinner" /> : children}
    </button>
  );
}

// Button.css: variantes con CSS o Tailwind
.btn { /* base */ padding: 0.5rem 1rem; border-radius: 8px; font-weight: 500; transition: all 0.2s; cursor: pointer; border: none; }
.btn-primary { background: var(--color-primario); color: white; }
.btn-primary:hover { background: var(--color-primario-hover); }
.btn-secondary { background: white; color: var(--color-texto); border: 1px solid var(--color-borde); }
.btn-danger { background: var(--color-error); color: white; }
.btn-ghost { background: transparent; color: var(--color-texto); }
.btn-sm { padding: 0.25rem 0.5rem; font-size: 0.875rem; }
.btn-md { padding: 0.5rem 1rem; font-size: 1rem; }
.btn-lg { padding: 0.75rem 1.5rem; font-size: 1.125rem; }
.btn-loading { opacity: 0.6; cursor: wait; }
.btn:disabled { opacity: 0.5; cursor: not-allowed; }

// Uso: el mismo Button en TODA la app
<Button variant="primary" size="md">Guardar</Button>
<Button variant="danger" size="sm" onClick={eliminar}>Eliminar</Button>
<Button variant="secondary" disabled>Cancelar</Button>
<Button variant="primary" loading>Enviando...</Button>

Átomo Button: el componente más reutilizado de tu app

3.6.3 Moléculas: SearchBar, FormField, Card

Las moléculas son combinaciones de átomos que forman una UNIDAD funcional. SearchBar = Input + Button + (opcional) Icon. FormField = Label + Input + (opcional) error message. Card = Image + Title + Description + (opcional) actions. Las moléculas tienen su PROPIA identidad: cuando ves una SearchBar, sabes que es 'el buscador', no solo 'un input con un botón al lado'.

Molécula SearchBar: input + botón con debounce integrado

// molecules/SearchBar.jsx
import { useState } from 'react';
import { useDebounce } from '../hooks/useDebounce';
import { Input } from '../atoms/Input';
import { Button } from '../atoms/Button';

export function SearchBar({ placeholder = 'Buscar...', onSearch, delay = 300 }) {
  const [termino, setTermino] = useState('');
  const terminoDebounced = useDebounce(termino, delay);

  // Cuando el debounced cambia, llama a onSearch
  if (onSearch && terminoDebounced) onSearch(terminoDebounced);

  return (
    <form className="search-bar" onSubmit={e => e.preventDefault()}>
      <Input
        type="search"
        placeholder={placeholder}
        value={termino}
        onChange={e => setTermino(e.target.value)}
      />
      <Button type="submit" variant="primary" size="md" disabled={!termino}>
        Buscar
      </Button>
    </form>
  );
}

// Molécula FormField: label + input + error message
// molecules/FormField.jsx
import { Input } from '../atoms/Input';

export function FormField({ label, name, type = 'text', value, onChange, error, required }) {
  return (
    <div className={`form-field ${error ? 'has-error' : ''}`}>
      <label htmlFor={name}>{label}{required && <span className="required">*</span>}</label>
      <Input id={name} name={name} type={type} value={value} onChange={onChange} />
      {error && <span className="error-message">{error}</span>}
    </div>
  );
}

// Uso:
<FormField
  label="Correo electrónico"
  name="email"
  type="email"
  value={email}
  onChange={e => setEmail(e.target.value)}
  error={errors.email}
  required
/>

Moléculas: SearchBar y FormField combinando átomos

3.6.4 Organismos: Header, UserCard, ProductList

Los organismos son SECCIONES COMPLETAS con su propia lógica y estado. Header (logo + nav + search + user menu) es un organismo: tiene estado (usuario autenticado o no, menú abierto o cerrado), combina moléculas (SearchBar) y átomos (Button, Avatar), y tiene una responsabilidad clara: la navegación principal. Los organismos son el corazón de tu app.

Organismo Header: nav + search + user menu

// organisms/Header.jsx
import { Link, NavLink } from 'react-router-dom';
import { useState } from 'react';
import { Button } from '../atoms/Button';
import { Avatar } from '../atoms/Avatar';
import { SearchBar } from '../molecules/SearchBar';

export function Header({ usuario, onLogout }) {
  const [menuAbierto, setMenuAbierto] = useState(false);

  return (
    <header className="app-header">
      <Link to="/" className="logo">🌍 Atlas Mundial</Link>

      <nav className="nav-links">
        <NavLink to="/" end>Inicio</NavLink>
        <NavLink to="/paises">Países</NavLink>
        <NavLink to="/mapa">Mapa</NavLink>
        <NavLink to="/sobre">Sobre</NavLink>
      </nav>

      <SearchBar onSearch={(q) => console.log('Buscar:', q)} />

      {usuario ? (
        <div className="user-menu">
          <button onClick={() => setMenuAbierto(!menuAbierto)}>
            <Avatar src={usuario.avatar} alt={usuario.nombre} />
          </button>
          {menuAbierto && (
            <div className="dropdown">
              <Link to="/perfil">Mi perfil</Link>
              <Link to="/favoritos">Favoritos</Link>
              <button onClick={onLogout}>Cerrar sesión</button>
            </div>
          )}
        </div>
      ) : (
        <Button variant="primary" size="sm">Iniciar sesión</Button>
      )}
    </header>
  );
}

Organismo Header: nav + search + user menu con estado

3.6.5 Templates y páginas: layout + instancias

Los templates son la ESTRUCTURA reutilizable sin contenido específico: layout principal con Header arriba, contenido en el medio, Footer abajo. Las páginas son las INSTANCIAS concretas del template con datos reales. Esta separación te permite cambiar todo el layout sin tocar las páginas, y cambiar una página sin tocar el layout. Es la separación de responsabilidades definitiva.

Template MainLayout: el esqueleto reutilizable

// templates/MainLayout.jsx: el template principal de tu app
import { Header } from '../organisms/Header';
import { Footer } from '../organisms/Footer';
import { Outlet } from 'react-router-dom';

export function MainLayout({ usuario, onLogout }) {
  return (
    <div className="app-layout">
      <Header usuario={usuario} onLogout={onLogout} />
      <main className="app-main">
        {/* Outlet renderiza el componente de la ruta activa */}
        <Outlet />
      </main>
      <Footer />
    </div>
  );
}

// pages/Home.jsx: una página concreta
import { useFetch } from '../hooks/useFetch';
import { SearchBar } from '../molecules/SearchBar';
import { PaisCard } from '../organisms/PaisCard';

export function Home() {
  const { data, cargando } = useFetch('https://restcountries.com/v3.1/all?fields=name,capital,population,flag,region,cca3');
  return (
    <div className="home-page">
      <h1>🌍 Explora el mundo</h1>
      <SearchBar onSearch={(q) => console.log(q)} />
      {cargando ? <p>Cargando...</p> : (
        <div className="paises-grid">
          {data?.slice(0, 20).map(pais => <PaisCard key={pais.cca3} pais={pais} />)}
        </div>
      )}
    </div>
  );
}

// App.jsx: usa MainLayout como template de TODAS las rutas
<Routes>
  <Route element={<MainLayout usuario={usuario} onLogout={logout} />}>
    <Route path="/" element={<Home />} />
    <Route path="/pais/:id" element={<DetallePais />} />
    <Route path="/sobre" element={<Sobre />} />
  </Route>
</Routes>

Template MainLayout y pages concretas con Outlet de React Router

3.6.6 Documentación de componentes con Storybook

Storybook es la herramienta estándar para documentar y testear componentes en aislamiento. Creas 'stories' para cada componente y cada variante, y tienes un catálogo vivo donde puedes ver cómo se ve tu Button primary, secondary, danger, disabled, loading, sin tener que navegar por toda tu app. Es lo que usan los equipos profesionales para mantener su design system. Vamos a configurarlo en Atlas Mundial.

Configurar Storybook en Vite + React

// Instalar: npx sb init --builder=vite
// Crea automáticamente la carpeta .storybook/ y stories/Button.stories.jsx

// stories/Button.stories.jsx: la documentación del Button
import { Button } from '../src/atoms/Button';

export default {
  title: 'Átomos/Button',
  component: Button,
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary', 'danger', 'ghost'] },
    size: { control: 'select', options: ['sm', 'md', 'lg'] },
    disabled: { control: 'boolean' },
    loading: { control: 'boolean' },
  },
};

// Cada 'export const' es una 'story': una variante del componente
export const Primary = { args: { variant: 'primary', children: 'Guardar' } };
export const Secondary = { args: { variant: 'secondary', children: 'Cancelar' } };
export const Danger = { args: { variant: 'danger', children: 'Eliminar' } };
export const Ghost = { args: { variant: 'ghost', children: 'Más info' } };
export const Small = { args: { size: 'sm', children: 'Pequeño' } };
export const Large = { args: { size: 'lg', children: 'Grande' } };
export const Disabled = { args: { disabled: true, children: 'Deshabilitado' } };
export const Loading = { args: { loading: true, children: 'Cargando' } };

// Para correrlo: npm run storybook
// Abre en http://localhost:6006 y verás TODAS las variantes de tu Button en un solo lugar.
// Puedes cambiar las props con los controles y ver el cambio en tiempo real.

Storybook: catálogo vivo de componentes

📚 Contenido ampliado

Material adicional, referencias externas verificadas y ejemplos extendidos.