Modo oscuro con prefers-color-scheme, color-scheme y light-dark()

Qué es

prefers-color-scheme es una característica de medios con los valores light y dark; MDN la describe como la detección de si el usuario solicitó un tema claro u oscuro mediante un ajuste del sistema operativo o del navegador. Solo responde a una pregunta. La propiedad color-scheme hace algo: declara en qué esquemas puede renderizarse un elemento (normal, light, dark, light dark, u only light para prohibir cambios), y MDN enumera lo que el navegador adapta entonces al esquema usado: la superficie del lienzo, los colores predeterminados de la barra de desplazamiento, los colores predeterminados de los controles de formulario y otros elementos de interfaz proporcionados por el navegador, como el subrayado del corrector ortográfico. <meta name="color-scheme" content="light dark"> en head, colocado antes de cualquier hoja de estilos, indica lo mismo al navegador antes de que llegue el CSS; MDN lo recomienda para evitar un parpadeo durante la carga de la página. Por último, light-dark(a, b) devuelve el primer color cuando el esquema usado es claro o no está definido, y el segundo cuando es oscuro, sin necesidad de media query; MDN indica que solo funciona cuando color-scheme tiene el valor light dark, normalmente establecido en :root.

Por qué importa

Una hoja de estilos que solo oscurece los fondos bajo la media query produce una página oscura con campos nativos blancos, barras de desplazamiento blancas y un parpadeo blanco antes de que se apliquen los estilos. Declarar color-scheme corrige las partes nativas; la media query y light-dark() se ocupan de los colores propios del autor.

Cómo aplicarlo

• Poner color-scheme: light dark en :root y la etiqueta meta equivalente en head; el navegador renderiza entonces correctamente los controles nativos en ambos esquemas.
• Definir la paleta como propiedades personalizadas en un solo lugar, ya sea con dos bloques (:root { … } @media (prefers-color-scheme: dark) { :root { … } }) o con light-dark() por cada token.
• Evitar el negro puro sobre blanco puro y viceversa; reducir la saturación de los colores de acento en la paleta oscura y comprobar el contraste en ambos esquemas, ya que una relación que pasa sobre blanco puede fallar sobre gris oscuro.
• Sustituir o recolorear las imágenes: <picture> con una fuente media="(prefers-color-scheme: dark)" para logotipos y diagramas; el SVG en línea puede usar currentColor.
• Para un interruptor manejado por el usuario, establecer una clase o un atributo data-theme en html mediante un script en línea que se ejecute antes del primer renderizado, guardar la elección y tratar "sistema" como el estado predeterminado.

Trampas

Las sombras desaparecen sobre fondos oscuros; la elevación necesita superficies más claras en su lugar. Los PNG transparentes asumen una página clara. Las incrustaciones de terceros y los iframes no heredan la elección. only light excluye a un elemento del esquema del usuario, lo cual rara vez está justificado.

Un interruptor también debe establecer color-scheme

Un interruptor de tema que solo intercambia propiedades personalizadas deja los controles nativos en el esquema del sistema operativo: página oscura, campos y barras de desplazamiento claros. Hay que hacer que el atributo también establezca color-scheme:

:root { color-scheme: light dark; }
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"] { color-scheme: dark; }

Con esto en su lugar, los tokens light-dark() siguen el interruptor automáticamente, porque la función se resuelve a partir del esquema de color usado del elemento; una paleta escrita como dos bloques prefers-color-scheme no lo hace, y necesita que su bloque oscuro se repita bajo [data-theme="dark"]. La elección guardada se aplica mediante un script en línea antes del primer renderizado (con un nonce o un hash bajo una Content Security Policy estricta), <meta name="color-scheme"> se actualiza desde el mismo script, y "sistema", que no establece ningún atributo, se mantiene como valor predeterminado.