Agregando Modo Oscuro a tu Sitio con Tailwind

Sep 23, 2025 · 4 min read

Agregando Modo Oscuro a tu Sitio con Tailwind

El modo oscuro no es solo una tendencia—es una expectativa del usuario. Sin embargo, muchos desarrolladores complican demasiado su implementación. Con Tailwind CSS, agregar modo oscuro a tu sitio requiere solo unas pocas líneas de código y cero dependencias de frameworks.

Este tutorial cubre tanto el modo oscuro automático (respetando las preferencias del sistema) como la alternancia manual con persistencia de preferencias del usuario. Aprenderás a implementar cualquiera de los dos enfoques en minutos usando la variante dark integrada de Tailwind.

Puntos Clave

La variante dark: de Tailwind habilita el modo oscuro con configuración mínima
El modo oscuro basado en el sistema funciona automáticamente sin JavaScript
Los toggles manuales dan a los usuarios control sobre su preferencia de visualización
localStorage previene el parpadeo de temas en las cargas de página

Cómo Funciona el Modo Oscuro en Tailwind CSS

La Variante dark: Explicada

Tailwind CSS proporciona una variante dark: que aplica estilos condicionalmente cuando el modo oscuro está activo. Simplemente prefija cualquier clase de utilidad con dark: para definir su apariencia en modo oscuro:

<div class="bg-white dark:bg-gray-900">
  <h1 class="text-gray-900 dark:text-white">Hello World</h1>
  <p class="text-gray-600 dark:text-gray-400">
    This text adapts to your theme preference
  </p>
</div>

Por defecto, Tailwind usa la media query CSS prefers-color-scheme para detectar la preferencia del sistema del usuario. No se necesita configuración—simplemente funciona.

Modo Oscuro Basado en el Sistema (Automático)

Usando prefers-color-scheme

La implementación de modo oscuro más simple no requiere JavaScript. Tailwind aplica automáticamente las utilidades de modo oscuro cuando el sistema operativo del usuario está configurado en modo oscuro:

<!-- Esta tarjeta será blanca en modo claro, gris oscuro en modo oscuro -->
<article class="bg-white dark:bg-gray-800 rounded-lg p-6 shadow-lg">
  <h2 class="text-xl font-bold text-gray-900 dark:text-white">
    Modo Oscuro Automático
  </h2>
  <p class="mt-2 text-gray-600 dark:text-gray-300">
    Este componente respeta la preferencia de tema de tu sistema
  </p>
</article>

Este enfoque funciona inmediatamente pero tiene una limitación: los usuarios no pueden anular su preferencia del sistema específicamente en tu sitio.

Toggle Manual de Modo Oscuro

Implementación Basada en Clases

Para dar control a los usuarios, configura Tailwind para usar una clase .dark en un elemento padre. Para Tailwind CSS v3.4 y posteriores, agrega esto a tu CSS:

@import "tailwindcss";

/* Para Tailwind CSS v4+ */
@custom-variant dark (&:where(.dark, .dark *));

Para versiones anteriores de Tailwind (v3.x), configúralo en tu tailwind.config.js:

module.exports = {
  darkMode: 'class',
  // ... resto de tu configuración
}

Ahora el modo oscuro se activa cuando la clase dark está presente en un elemento padre:

<html class="dark">
  <body>
    <div class="bg-white dark:bg-black">
      <!-- El modo oscuro está activo -->
    </div>
  </body>
</html>

Alterna el modo oscuro con este JavaScript:

// Alternar modo oscuro
document.documentElement.classList.toggle('dark');

Método de Atributo de Datos

Algunos desarrolladores prefieren atributos de datos para la gestión de temas. Configura Tailwind para usar data-theme:

@import "tailwindcss";

/* Para Tailwind CSS v4+ */
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

Luego controla el modo oscuro mediante el atributo:

<html data-theme="dark">
  <body>
    <div class="bg-white dark:bg-black">
      <!-- Modo oscuro activo cuando data-theme="dark" -->
    </div>
  </body>
</html>

Persistiendo la Preferencia del Usuario

Implementación con localStorage

Los usuarios esperan que su elección de tema persista. Aquí tienes una solución completa que recuerda las preferencias mientras respeta los valores predeterminados del sistema:

// Verificar preferencia guardada o usar predeterminado del sistema
function getThemePreference() {
  const savedTheme = localStorage.getItem('theme');
  if (savedTheme) {
    return savedTheme;
  }
  return window.matchMedia('(prefers-color-scheme: dark)').matches 
    ? 'dark' 
    : 'light';
}

// Aplicar tema al cargar
function applyTheme(theme) {
  if (theme === 'dark') {
    document.documentElement.classList.add('dark');
  } else {
    document.documentElement.classList.remove('dark');
  }
}

// Inicializar tema
applyTheme(getThemePreference());

// Función de alternancia de tema
function toggleTheme() {
  const currentTheme = document.documentElement.classList.contains('dark') 
    ? 'dark' 
    : 'light';
  const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
  
  applyTheme(newTheme);
  localStorage.setItem('theme', newTheme);
}

Para prevenir un destello de tema incorrecto al cargar la página, agrega este script inline a tu <head>:

<script>
  // Prevenir FOUC (Flash of Unstyled Content)
  if (localStorage.theme === 'dark' || 
      (!localStorage.theme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
    document.documentElement.classList.add('dark');
  }
</script>

Mejores Prácticas para Modo Oscuro con Tailwind

Rendimiento: Coloca los scripts de detección de tema en el <head> para prevenir cambios de diseño. El script inline anterior se ejecuta antes de que la página se renderice.

Accesibilidad: Asegura suficiente contraste de color en ambos temas. El modo oscuro no se trata solo de invertir colores—mantén la legibilidad con ratios de contraste apropiados (el estándar WCAG AA recomienda 4.5:1 para texto normal).

Pruebas: Siempre prueba ambos temas durante el desarrollo. Usa las DevTools del navegador para alternar rápidamente prefers-color-scheme sin cambiar la configuración del sistema.

Consistencia de Color: Usa la paleta de colores de Tailwind sistemáticamente. Por ejemplo, si usas gray-100 para fondos claros, considera gray-800 o gray-900 para los equivalentes de modo oscuro.

Conclusión

Implementar modo oscuro con Tailwind CSS requiere código mínimo y ninguna dependencia externa. Ya sea que elijas el modo basado en el sistema o la alternancia manual, la variante dark hace que el estilo consciente del tema sea directo. Comienza con modo oscuro automático para simplicidad, luego agrega controles manuales cuando los usuarios necesiten más control sobre su experiencia de visualización.

Preguntas Frecuentes

Sí, puedes implementar un toggle de tres vías que ofrezca opciones de claro, oscuro y sistema. Almacena la elección del usuario en localStorage y verifica si seleccionaron el modo sistema para respetar las preferencias del SO.

Usa filtros CSS para ajustes simples o proporciona fuentes de imagen alternativas. Para íconos, considera usar currentColor en SVGs para que hereden el color del texto, o aplica ajustes de opacidad con utilidades de Tailwind.

Absolutamente. La variante dark funciona con cualquier utilidad de Tailwind, incluyendo colores personalizados definidos en tu configuración. Solo prefija cualquier clase con dark: para aplicarla condicionalmente en modo oscuro.

Mínimo. La variante dark solo agrega reglas CSS, no sobrecarga de JavaScript. La consideración principal es prevenir el destello de contenido sin estilo cargando scripts de detección de tema temprano en el head del documento.

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.