Tema oscuro en Tailwind CSS v4: claro, oscuro y sistema

Autor: Pablo Mayoral Publicado: 19/11/2026 Actualizado: 19/11/2026

Un ajuste de tres opciones con una regla de resolución, un selector raíz y pruebas concretas de recargas y cambios del dispositivo.

Tema oscuro en Tailwind CSS v4: claro, oscuro y sistema
Resumen Directo

Separa la preferencia seleccionada del tema resuelto. Usa un selector raíz data-theme, da prioridad a la elección explícita y sigue el dispositivo solo con Sistema. Revisa persistencia, primera aparición y funcionamiento del control en la implementación.

Un tema oscuro en Tailwind CSS v4 necesita separar dos decisiones: qué apariencia ha elegido la persona y cuál debe mostrar la página ahora. Conserva la preferencia claro, oscuro o sistema, resuélvela a claro u oscuro y utiliza ese resultado para activar las utilidades. Así puedes explicar tanto una elección manual como un cambio posterior del dispositivo.

Resuelve la preferencia antes de pintar

Empieza con una tabla de decisión pequeña. Si la elección es Claro, muestra claro independientemente del sistema operativo. Si es Oscuro, muestra oscuro. Solo Sistema delega el resultado en la preferencia del dispositivo. Conserva esa elección visible aunque la página tenga ahora una apariencia oscura.

Dos elecciones explícitas y una entrada del sistema convergen en una apariencia clara u oscura.
Propuesta de Harbor: la elección explícita tiene prioridad; Sistema delega el resultado en el dispositivo.

La guía propone un ajuste para Harbor, un espacio ficticio de gestión de reservas. Su personal podría utilizar un ordenador compartido en recepción y después un portátil personal. El ejercicio guarda una preferencia local del navegador; no plantea un ajuste de cuenta que siga automáticamente a la persona entre dispositivos. Harbor y sus supuestos usuarios son inventados.

Elección guardadaApariencia del sistemaResultado visible
ClaroCualquieraClaro
OscuroCualquieraOscuro
SistemaClaroClaro
SistemaOscuroOscuro

No sustituyas el valor seleccionado por el resultado calculado. Si Sistema se convierte en Oscuro dentro del campo de ajustes, quien revisa no sabrá si la persona pidió oscuridad o delegó la decisión. Cuando cambie el sistema operativo, la interfaz podría parecer incoherente con lo que dice su propio campo.

Utiliza etiquetas directas: Claro, Oscuro y Sistema. Una explicación como «Sistema sigue la apariencia de este dispositivo» concreta el alcance. En los criterios de aceptación, distingue elegir Oscuro de elegir Sistema cuando el dispositivo ya está oscuro. Son estados diferentes aunque produzcan capturas iguales.

Para consultar la señal del dispositivo, MDN documenta matchMedia() y su propiedad matches. Harbor utiliza esa consulta como entrada del cálculo. Aquí recomendamos dar un único responsable a la resolución de apariencia, evitando que cabecera, ajustes y tarjetas decidan por separado qué tema debe estar activo.

Conecta un selector con la página

Escoge un contrato de activación y mantenlo en toda la página. La implementación propuesta escribe el valor resuelto en data-theme sobre el elemento raíz. Cada componente puede usar la apariencia activa sin averiguar si procede de una preferencia guardada o del sistema operativo.

Atributo raíz junto a tarjeta propia y campo nativo con responsabilidades de estilo separadas.
Un atributo raíz activa los estilos propios; los campos nativos necesitan además un color-scheme adecuado.

La documentación de modo oscuro de Tailwind muestra cómo redefinir la variante con un selector de atributo. El siguiente CSS sigue esa forma documentada. Inclúyelo en la hoja global que entra realmente en la compilación, no en un archivo suelto junto a una exportación del diseño.

@import "tailwindcss";
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

Da después un tratamiento explícito a un ejemplo. Una tarjeta de reserva puede partir de bg-white text-slate-900 border-slate-200 y añadir dark:bg-slate-900 dark:text-slate-100 dark:border-slate-700. Son una propuesta inicial para revisar, no una garantía sobre todas las combinaciones que pueda contener la tarjeta definitiva.

Separa los controles que dibuja el navegador de tus superficies personalizadas. Las utilidades color-scheme de Tailwind permiten acompañar la apariencia activa con scheme-light dark:scheme-dark en la raíz. Eso no recolorea todos los componentes propios. Revisa un campo de fecha, un selector y tu tarjeta antes de dar el conjunto por terminado.

Demuestra primero la conexión. Establece manualmente el atributo raíz en light, observa la tarjeta y después cambia a dark. Si nada varía, revisa la hoja cargada y el selector antes de investigar almacenamiento. Si solo falla una tarjeta anidada, busca otro límite data-theme dentro de la página.

Conserva los nombres completos de las clases en el ejemplo y evita construir las utilidades oscuras concatenando fragmentos durante la ejecución. Para ampliar la revisión visual de campos y estados, continúa con las clases de color de Tailwind para formularios, foco y estados. El cálculo de preferencia debe poder entenderse sin leer las clases de cada componente.

Ofrece claro, oscuro y sistema

Utiliza un control que muestre las tres opciones con palabras. En este ejercicio, un select nativo etiquetado mantiene compacto el ajuste y deja espacio para explicar su alcance. Evita representar Sistema mediante una tercera posición sin nombre entre un sol y una luna.

Selector Apariencia abierto con claro, oscuro y sistema junto a notas de selección y ayuda.
Campo Apariencia propuesto: Sistema sigue seleccionado aunque cambie la apariencia resuelta.

La referencia de select de MDN explica el control y sus opciones. El campo propuesto se llama Apariencia y utiliza los valores light, dark y system. Su valor seleccionado refleja la variable choice. Conecta su evento change con chooseAppearance(event.target.value) cuando el control exista e inicializa su valor a partir de choice.

Las funciones siguientes forman un controlador pequeño y original para este artículo. Validan los valores recibidos, conservan una elección en memoria aunque falle el guardado y escriben en el documento únicamente la apariencia resuelta. Es un esquema de integración; no es un paquete para un framework ni una afirmación de pruebas en producción.

const system = window.matchMedia("(prefers-color-scheme: dark)");
let choice = "system";
try {
  const stored = localStorage.getItem("appearance");
  if (stored === "light" || stored === "dark") choice = stored;
} catch {}

function applyAppearance() {
  const resolved = choice === "system"
    ? (system.matches ? "dark" : "light") : choice;
  document.documentElement.dataset.theme = resolved;
}
function chooseAppearance(next) {
  if (!["light", "dark", "system"].includes(next)) return;
  choice = next;
  try {
    if (next === "system") localStorage.removeItem("appearance");
    else localStorage.setItem("appearance", next);
  } catch {}
  applyAppearance();
}
system.addEventListener("change", () => {
  if (choice === "system") applyAppearance();
});
applyAppearance();

Coloca el ajuste donde pueda encontrarse de nuevo. En Harbor, Apariencia pertenece a los ajustes personales, con un acceso claro desde el menú de cuenta. Si también hay un acceso rápido en la cabecera, ambos controles deben mostrar la misma elección y utilizar el mismo responsable de estado.

Distingue entre cambiar la apariencia y conseguir guardarla. MDN documenta la persistencia y las restricciones de localStorage. Un navegador restringido puede rechazar el acceso. El controlador aún actualiza la página actual, pero no puede prometer que recuerde la elección tras recargar. Si esta diferencia afecta al producto, informa del guardado sin presentarlo como una preferencia duradera de cuenta.

Aplica los cambios del sistema con criterio

Reacciona a un cambio del dispositivo solamente cuando esté seleccionado Sistema. Una elección explícita tiene prioridad; un cambio posterior del sistema operativo no debería quitársela. Esta condición pertenece al controlador, no al aspecto visual de un botón concreto.

Evento de cambio del dispositivo: resolver con Sistema o conservar la elección manual.
Un cambio del dispositivo actualiza la página solo con Sistema. Las elecciones Claro y Oscuro conservan la prioridad.

El evento change de MediaQueryList permite recibir un cambio en el resultado de la consulta. En el esquema, el listener llama a applyAppearance únicamente con la elección system. Pasar de Oscuro a Sistema resuelve inmediatamente la apariencia actual del dispositivo: no espera a que se produzca otro cambio.

Prueba una secuencia breve. Empieza con el dispositivo oscuro y selecciona Claro en Harbor. Cambia el dispositivo a claro y después a oscuro; Harbor debe seguir claro. Selecciona Sistema y confirma que se aplica el estado actual del dispositivo. Vuelve a cambiar el dispositivo y observa que Harbor ahora sí lo sigue.

Mantén veraz el texto del ajuste durante toda la secuencia. El campo debe continuar mostrando Sistema mientras la página pasa de claro a oscuro. Si añades un texto como «Ahora: oscuro», preséntalo aparte de la elección seleccionada. Así se entiende el resultado sin perder la causa que lo gobierna.

En un framework de componentes, registra el listener una vez en el límite adecuado de la aplicación y elimínalo cuando desaparezca su responsable. Evita añadir otro cada vez que se abren los ajustes. El esquema independiente asume un controlador durante la vida de la página; su adaptación necesita gestionar el ciclo de vida.

Decide también hasta dónde llega la sincronización. Este ejemplo no coordina varias pestañas ni un perfil del servidor. Si Harbor lo necesita, registra requisitos separados. Una preferencia local que funciona en una pestaña puede ser una entrega válida siempre que interfaz y documentación describan ese alcance con precisión.

Prueba recargas y la primera aparición

Prueba la recarga como una transición independiente. Un tema que funciona al hacer clic puede empezar mostrando una superficie equivocada antes de aplicar la preferencia. Revisa una navegación nueva, una recarga y una visita posterior, anotando la elección guardada en cada caso.

Tres etapas de recarga conservan Claro con dispositivo oscuro y revisan el aspecto inicial.
Prueba propuesta: Claro guardado debe seguir claro con dispositivo oscuro, también en la apariencia inicial.

Ejecuta la resolución inicial con suficiente antelación para tu modelo de entrega y utiliza la misma regla que en el controlador interactivo. En una página renderizada en cliente, un paso de arranque pequeño puede aplicar el atributo antes de pintar el contenido principal. Con renderizado en servidor, acuerda cómo comparten la preferencia la salida inicial y el arranque del cliente.

El esquema no prescribe una reparación de hidratación para un framework concreto. Si el servidor no puede leer el almacenamiento del navegador, documenta el estado inicial y observa el primer fotograma. Evita repartir indicadores de supresión y scripts duplicados para ocultar una contradicción que sigue existiendo en el modelo de preferencia.

Caso de revisiónObservación esperada
Claro guardado, dispositivo oscuroClaro se conserva al recargar
Oscuro guardado, dispositivo claroOscuro se conserva al recargar
Sistema, cambia el dispositivoLa página abierta sigue el cambio
Almacenamiento denegadoLa elección funciona durante esta sesión de página
Valor guardado desconocidoSe utiliza Sistema

Captura los resultados con la misma reserva y el mismo ancho. Comparar antes y después resulta confuso si también cambian contenido, tamaño o validación. En la ficha de revisión, anota elección seleccionada, tema resuelto, apariencia del dispositivo y si hubo navegación.

Describe el fallo mediante la transición concreta: «Claro guardado, dispositivo oscuro, la recarga muestra oscuro un instante y termina en claro». Desarrollo recibe así un punto reproducible. «El modo oscuro falla» no permite distinguir entre inicialización, selector, almacenamiento y tratamiento de una superficie específica.

Revisa un control de EmviUI en ambos temas

Utiliza el ejemplo real select-dropdown de EmviUI para revisar etiqueta, valor actual, ayuda y jerarquía del menú abierto. Las muestras incluyen etiquetas genéricas y opciones de plataformas. Sirven como punto de partida visual para Apariencia; no representan un controlador de tema ya implementado.

Ejemplo select-dropdown de EmviUI con etiquetas, ayuda, valores seleccionados y menús de plataformas abiertos.
Ejemplo real select-dropdown de EmviUI. Adapta etiqueta y opciones para Apariencia; la imagen no implementa el cambio de tema.

EmviUI describe su kit de Figma y el soporte de modo oscuro. Sustituye el texto genérico por Apariencia y las tres opciones, y compara el control cerrado con su lista abierta sobre las superficies previstas. Mantén legible la ayuda en ambos temas y distingue con claridad el valor elegido de la etiqueta del campo.

Comprueba las combinaciones de texto renderizadas. El criterio de contraste mínimo de WCAG pide 4,5:1 para texto normal y 3:1 para texto grande que cumpla la definición, con excepciones especificadas. Una paleta de aspecto oscuro no acredita esos resultados. Mide etiqueta, valor y ayuda frente a sus fondos inmediatos.

Recorre la selección mediante teclado y el foco en la implementación, incluyendo qué ocurre si cambia la apariencia con el menú abierto. El ejemplo estático no demuestra esos comportamientos. Registra un resultado concreto por estado en lugar de aprobar todo el control a partir de una captura atractiva.

Mantén acotada la entrega: tabla de decisión, contrato del selector raíz, tres valores y casos de recarga. Si el problema está en las vinculaciones del diseño, continúa con cómo rastrear vínculos y herencia de modos en Figma. Esa investigación complementa el modelo del navegador y permite revisar cada responsabilidad en su entorno.

Cierra con un criterio verificable: Harbor conserva una elección explícita, sigue el dispositivo solo con Sistema y presenta un ajuste legible y operable en ambas apariencias. Adjunta los casos observados y los límites pendientes. Esa entrega informa mejor que contar cuántas clases oscuras aparecen en la página.

Pablo Mayoral

Diseñador UX/UI y Web con más de 10 años de experiencia. Creador de EmviUI (sistema de diseño en Figma con más de 10k componentes), UImand y Vitamin Bootstrap. Diseñando actualmente productos digitales en CQMRewards.

Preguntas frecuentes

¿Tailwind v4 guarda automáticamente la elección de tema? ▼
No. La variante dark aporta condiciones de estilo. El controlador del artículo gestiona elección y almacenamiento por separado; las restricciones del navegador pueden impedir la persistencia.
¿Por qué mantener Sistema si la página se ve oscura? ▼
Sistema es la elección de la persona y oscuro es el resultado resuelto. Separarlos permite seguir cambios posteriores del dispositivo sin atribuir una elección manual que no se hizo.
¿Por qué el dispositivo reemplaza mi elección manual? ▼
Comprueba si el listener aplica el resultado del sistema sin condición. El controlador propuesto solo vuelve a resolver desde ese evento cuando choice vale system, conservando la prioridad de Claro u Oscuro.
¿color-scheme cambia todas mis tarjetas personalizadas? ▼
Controla la apariencia que aporta el navegador. Define y revisa los estilos de las superficies propias. Tailwind documenta combinar scheme-light con dark:scheme-dark para el renderizado nativo.
¿Qué ocurre si localStorage no está disponible? ▼
MDN documenta restricciones de acceso. El esquema captura los errores y mantiene la selección actual en memoria; no garantiza conservarla en la siguiente carga de página.
¿Un ejemplo de Figma de EmviUI demuestra que funciona? ▼
No. Utilízalo para revisar etiqueta, valor, ayuda y menú. Comprueba almacenamiento, cambios del dispositivo, recargas, teclado y contraste de texto en la página implementada.

Artículos relacionados