Tema oscuro en Tailwind CSS v4: claro, oscuro y sistema
Un ajuste de tres opciones con una regla de resolución, un selector raíz y pruebas concretas de recargas y cambios del dispositivo.
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.

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 guardada | Apariencia del sistema | Resultado visible |
|---|---|---|
| Claro | Cualquiera | Claro |
| Oscuro | Cualquiera | Oscuro |
| Sistema | Claro | Claro |
| Sistema | Oscuro | Oscuro |
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.

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.

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.

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.

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ón | Observación esperada |
|---|---|
| Claro guardado, dispositivo oscuro | Claro se conserva al recargar |
| Oscuro guardado, dispositivo claro | Oscuro se conserva al recargar |
| Sistema, cambia el dispositivo | La página abierta sigue el cambio |
| Almacenamiento denegado | La elección funciona durante esta sesión de página |
| Valor guardado desconocido | Se 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.

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.