La mayoria de tutoriales de Tailwind CSS se quedan en lo basico: aplicar bg-blue-500 a un div y declarar victoria. Pero cuando trabajas en un proyecto real con multiples paginas, varios desarrolladores y la necesidad de mantener consistencia visual, necesitas un sistema. Las clases utilitarias son la herramienta, no la estrategia.
Un sistema de diseno con Tailwind implica tres capas: tokens de diseno como fuente de verdad, mapeo de esos tokens a utilidades de Tailwind, y patrones de componentes que consumen esas utilidades de forma predecible.
Los design tokens son los valores atomicos de tu sistema: colores, espaciados, tamanos de fuente, radios de borde. En lugar de hardcodear valores en la configuracion de Tailwind, defines CSS custom properties que actuan como capa de abstraccion.
/* globals.css */
:root {
/* Colores semanticos, no descriptivos */
--color-bg: #0e0d0c;
--color-bg-elevated: #1a1917;
--color-text: #ece6df;
--color-text-secondary: #a89f94;
--color-text-muted: #6b6460;
--color-accent: #c9553d;
--color-accent-hover: #d4674f;
--color-border: #2a2725;
--color-surface: #161514;
/* Espaciado basado en una escala de 4px */
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-6: 24px;
--space-8: 32px;
--space-12: 48px;
--space-16: 64px;
--space-24: 96px;
/* Radios de borde */
--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 16px;
--radius-full: 9999px;
}
Lo clave es que los nombres son semanticos, no descriptivos. Usamos --color-bg-elevated en vez de --color-dark-gray. Cuando cambies de tema o ajustes la paleta, el significado de cada token se mantiene aunque su valor cambie.
Tailwind CSS 4 introdujo la directiva @theme inline que permite referenciar CSS custom properties directamente como tokens de Tailwind:
@theme inline {
--color-bg: var(--color-bg);
--color-bg-elevated: var(--color-bg-elevated);
--color-text: var(--color-text);
--color-text-secondary: var(--color-text-secondary);
--color-text-muted: var(--color-text-muted);
--color-accent: var(--color-accent);
--color-accent-hover: var(--color-accent-hover);
--color-border: var(--color-border);
--color-surface: var(--color-surface);
}
Ahora puedes usar clases como bg-bg, text-text-secondary, border-border en tus componentes. El pipeline completo es: variable CSS -> token Tailwind -> clase utilitaria en HTML. Si manana cambias --color-accent de terracota a azul, toda la interfaz se actualiza sin tocar un solo componente.
Para implementar modo oscuro y claro, la estrategia class da control total. En Tailwind CSS 4, el dark mode por clase ya viene habilitado. Defines las variables para cada tema:
:root {
--color-bg: #0e0d0c;
--color-text: #ece6df;
--color-text-secondary: #a89f94;
--color-border: #2a2725;
--color-surface: #161514;
}
:root.light {
--color-bg: #f5f0eb;
--color-text: #1a1614;
--color-text-secondary: #5c5550;
--color-border: #d9d0c7;
--color-surface: #ffffff;
}
El cambio de tema se reduce a agregar o quitar la clase light en el elemento <html>. Ningun componente necesita saber que existen multiples temas. Simplemente usan bg-bg o text-text y las variables CSS hacen el resto.
Para persistir la preferencia del usuario:
function toggleTheme() {
const html = document.documentElement;
const isLight = html.classList.toggle('light');
localStorage.setItem('theme', isLight ? 'light' : 'dark');
}
// Al cargar la pagina
const saved = localStorage.getItem('theme');
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
if (saved === 'light' || (!saved && !prefersDark)) {
document.documentElement.classList.add('light');
}
Este script debe ejecutarse lo antes posible (idealmente en un <script> en el <head>) para evitar el flash de tema incorrecto (FOIT/FOUT analogo para temas).
Las media queries para tipografia crean saltos abruptos entre breakpoints. La funcion clamp() resuelve esto con una transicion fluida:
:root {
--text-xs: clamp(11px, 0.75vw, 12px);
--text-sm: clamp(13px, 0.85vw, 14px);
--text-base: clamp(15px, 1vw, 16px);
--text-lg: clamp(17px, 1.15vw, 18px);
--text-xl: clamp(19px, 1.3vw, 20px);
--text-2xl: clamp(23px, 1.6vw, 24px);
--text-3xl: clamp(28px, 2.2vw, 30px);
--text-4xl: clamp(34px, 3vw, 36px);
--text-hero: clamp(36px, 5vw, 56px);
}
La formula es clamp(minimo, valor_preferido, maximo). El valor preferido usa unidades de viewport (vw) para que escale con el ancho de la pantalla, pero nunca baja del minimo ni supera el maximo. Esto elimina la necesidad de definir tamanos por breakpoint como text-sm md:text-base lg:text-lg.
Mapea estos tokens a Tailwind y usarlos se vuelve natural:
<h1 class="text-hero font-serif italic">Titulo principal</h1>
<p class="text-base text-text-secondary">Parrafo de contenido</p>
Cuando un grupo de clases se repite consistentemente, tienes dos opciones: extraer a un componente (React, Vue, etc.) o usar @apply. La regla general: prefiere componentes sobre @apply.
@apply tiene su lugar para elementos que no justifican un componente completo, como estilos base de elementos HTML:
/* Esto esta bien: estilos base para prose/markdown */
.prose h2 {
@apply text-2xl font-serif font-semibold text-text mt-12 mb-4;
}
.prose p {
@apply text-base text-text-secondary leading-relaxed mb-6;
}
.prose code {
@apply bg-bg-elevated text-accent px-1.5 py-0.5 rounded-sm text-sm;
}
Para componentes interactivos, la extraccion a componentes es siempre mejor. Un boton con variantes:
function Button({ variant = 'primary', size = 'md', children, ...props }) {
const base = 'inline-flex items-center justify-center font-medium transition-colors rounded-md focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent';
const variants = {
primary: 'bg-accent text-white hover:bg-accent-hover',
secondary: 'bg-bg-elevated text-text border border-border hover:border-text-muted',
ghost: 'text-text-secondary hover:text-text hover:bg-bg-elevated',
};
const sizes = {
sm: 'px-3 py-1.5 text-sm',
md: 'px-4 py-2 text-base',
lg: 'px-6 py-3 text-lg',
};
return (
<button className={`${base} ${variants[variant]} ${sizes[size]}`} {...props}>
{children}
</button>
);
}
Este patron escala bien. Cada variante es una combinacion predecible de utilidades. Agregar una nueva variante es agregar una linea al objeto, no crear una clase CSS nueva.
Las cards aparecen en todo sistema de diseno. Un patron robusto con Tailwind:
function Card({ children, hover = false, className = '' }) {
return (
<div className={`
bg-surface rounded-lg border border-border p-6
${hover ? 'transition-all hover:border-text-muted hover:shadow-lg hover:-translate-y-0.5' : ''}
${className}
`}>
{children}
</div>
);
}
function CardHeader({ title, subtitle }) {
return (
<div className="mb-4">
<h3 className="text-lg font-semibold text-text">{title}</h3>
{subtitle && <p className="text-sm text-text-muted mt-1">{subtitle}</p>}
</div>
);
}
La composicion Card + CardHeader + contenido libre permite flexibilidad sin perder consistencia. Todas las cards del sistema comparten el mismo borde, radio, padding y comportamiento hover.
Tailwind facilita el responsive design con prefijos como md: y lg:, pero un error comun es abusar de ellos. Si tienes text-sm md:text-base lg:text-lg xl:text-xl en cada elemento, tu HTML se vuelve ilegible.
Estrategias para mantener la sanidad:
1. Contenedores con ancho maximo contextual
<main class="max-w-3xl mx-auto px-4 sm:px-6">
<!-- Todo el contenido hereda el ancho maximo -->
</main>
2. Grids que se adaptan automaticamente
<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
<!-- Las cards se redistribuyen sin clases individuales -->
</div>
3. Tamanos fluidos con clamp() en vez de breakpoints
Como vimos en la seccion de tipografia, clamp() elimina la necesidad de multiples breakpoints para valores que deben escalar continuamente.
Valores arbitrarios excesivos. Si tu codigo tiene p-[13px] o mt-[7px], tu escala de espaciado no esta bien definida. Los valores arbitrarios deberian ser excepciones raras, no la norma. Si necesitas 13px frecuentemente, agregalo como token.
Espaciado inconsistente. Definir una escala base (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px) y adherirse a ella previene el caos visual. Todo espaciado deberia ser multiplo de 4.
Colores magicos. bg-[#3a7bd5] disperso por el codigo hace imposible mantener la consistencia. Todo color deberia ser un token semantico.
@apply para todo. Usar @apply para crear .btn-primary niega el proposito de Tailwind. Si necesitas abstracciones, crea componentes. Reserva @apply para estilos base de elementos HTML y contenido generado (como Markdown renderizado).
En proyectos con muchos componentes, organizo los estilos en capas:
/* 1. Tokens: variables CSS */
@import './tokens.css';
/* 2. Tailwind */
@import 'tailwindcss';
/* 3. Mapeo de tokens a Tailwind */
@theme inline { /* ... */ }
/* 4. Estilos base (reset, tipografia global) */
@layer base { /* ... */ }
/* 5. Estilos de componentes que no justifican componentes JS */
@layer components { /* ... */ }
Esta separacion hace que cada capa sea predecible. Los tokens viven en un archivo, el mapeo en otro, y los overrides en su propia capa. Cuando alguien nuevo se une al proyecto, la estructura le indica exactamente donde buscar y donde agregar cosas.
La clave de un sistema de diseno exitoso con Tailwind no son las clases utilitarias individuales, sino la disciplina de mantener una fuente de verdad (tokens), consumirla consistentemente (mapeo a utilidades), y abstraer patrones repetitivos (componentes). Las herramientas estan todas ahi; lo que marca la diferencia es la arquitectura de decision.