Modos dark/light en Tailwind CSS v4 (migrando desde v3 con @config)

Actualizado a Tailwind v4. La versión original usaba addBase dentro de tailwind.config.mjs (patrón de v3). Al migrar a v4 lo pasé a CSS, pero mantuve mi config de colores cargándola con @config — una migración de fricción mínima. El concepto —variables CSS en :root/.dark— es el mismo; cambia el cómo.

Cuando trabajo con plantillas multitema, mantener los colores coherentes entre componentes es un reto. Tras varias experiencias con inconsistencias, encontré una solución fácil y escalable: definir los colores como variables CSS en :root y .dark, y exponerlos como utilidades de Tailwind.

Colores y temas bajo control

En Tailwind v4 puedes seguir usando tu config JS cargándola con @config, y centralizar la paleta como variables CSS en @layer base:

/* global.css */
@import "tailwindcss";
@config "../../tailwind.config.mjs";

@layer base {
  :root {
    --color-background: #fefefe;
    --color-foreground: #0f0f0f;
  }
  .dark {
    --color-background: #1d1e26;
    --color-foreground: #e8eaf0;
  }
}

En el config mantengo el darkMode: "class" y mapeo cada color a su variable, para que Tailwind genere utilidades como bg-background o text-foreground:

// tailwind.config.mjs
export default {
  darkMode: "class",
  theme: {
    extend: {
      colors: {
        background: "var(--color-background)",
        foreground: "var(--color-foreground)",
      },
    },
  },
};

Con esto centralizo mi paleta en un único sitio y gestiono light y dark sin esfuerzo. Un cambio en una variable y todo se actualiza al instante, sin buscar y reemplazar por mil archivos. Alternar temas es tan simple como añadir la clase .dark en el <html>.

Rendimiento y mantenimiento

El motor de v4 (Oxide, escrito en Rust) hace builds notablemente más rápidos y detecta clases automáticamente. Y cargar el config con @config te deja migrar desde v3 sin reescribir toda la paleta: darkMode y el mapeo de colores siguen donde estaban, y las variables viven en el CSS. Resultado: menos inconsistencias y menos tiempo perdido buscando valores sueltos.

Conclusión

Variables CSS en :root/.dark + el config cargado con @config me dan consistencia, rendimiento y temas dinámicos con una migración a v4 casi indolora. Simplifica el mantenimiento y mantiene las plantillas coherentes. Si te importa el código mantenible y una UX consistente, es un enfoque por defecto que merece la pena adoptar.