Construir design systems escalables con React y Tailwind

Los design systems son la columna vertebral de las interfaces consistentes. Así es como construir uno que escale.

Por qué importan los design systems

Un design system bien elaborado aporta:

Consistencia en todos los productos
Desarrollo más rápido con componentes reutilizables
Mejor colaboración entre diseñadores y desarrolladores
Menos deuda técnica con el tiempo

Principios clave

1. Empieza con tokens

Los design tokens son los valores atómicos de tu sistema:

export const tokens = {
  colors: {
    primary: {
      50: '#eff6ff',
      500: '#3b82f6',
      900: '#1e3a8a',
    },
    neutral: {
      0: '#ffffff',
      100: '#f5f5f5',
      900: '#171717',
    },
  },
  spacing: {
    xs: '0.25rem',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
    xl: '2rem',
  },
  radii: {
    sm: '0.25rem',
    md: '0.5rem',
    lg: '1rem',
    full: '9999px',
  },
} as const;

2. Construye componentes primitivos

Empieza por lo básico:

import { cva, type VariantProps } from "class-variance-authority";

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md font-medium transition-colors",
  {
    variants: {
      variant: {
        primary: "bg-primary text-white hover:bg-primary/90",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
      },
      size: {
        sm: "h-8 px-3 text-sm",
        md: "h-10 px-4",
        lg: "h-12 px-6 text-lg",
      },
    },
    defaultVariants: {
      variant: "primary",
      size: "md",
    },
  }
);

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

export function Button({ variant, size, className, ...props }: ButtonProps) {
  return (
    <button className={buttonVariants({ variant, size, className })} {...props} />
  );
}

Composición de componentes

Construye componentes complejos a partir de primitivos:

Nivel	Ejemplos	Propósito
Tokens	Colores, espaciado, tipografía	Fundación
Primitivos	Button, Input, Badge	Bloques de construcción
Patrones	Card, Modal, Dropdown	Patrones comunes de UI
Plantillas	PageHeader, Sidebar	Estructuras de layout

La documentación es clave

"Un design system sin documentación es solo una librería de componentes."

Cada componente debería incluir:

Ejemplos de uso - Muestra casos comunes
Documentación de props - Explica todas las opciones
Notas de accesibilidad - Etiquetas ARIA, navegación por teclado
Qué hacer y qué no - Guía el uso correcto

Estrategia de versionado

{
  "name": "@company/design-system",
  "version": "2.1.0",
  "peerDependencies": {
    "react": "^18.0.0",
    "tailwindcss": "^3.0.0"
  }
}

Usa versionado semántico:

Major: Cambios incompatibles
Minor: Nuevas funciones (compatibles hacia atrás)
Patch: Correcciones de errores

Conclusión

Construir un design system es una inversión que rinde en:

Productividad del desarrollador
Consistencia de diseño
Experiencia de usuario
Colaboración del equipo

Empieza pequeño, itera seguido y documenta todo.