Modo escuro com prefers-color-scheme, color-scheme e light-dark()

O que é

prefers-color-scheme é uma media feature com os valores light e dark; a MDN a descreve como a forma de detectar se o usuário pediu um tema claro ou escuro por meio de uma configuração do sistema operacional ou do navegador. Ela apenas responde a uma pergunta. Quem realmente faz algo é a propriedade color-scheme: ela declara em quais esquemas um elemento pode ser renderizado (normal, light, dark, light dark ou only light, que proíbe sobrescritas). A MDN lista o que o navegador passa a adaptar ao esquema em uso: a superfície do canvas, as cores padrão das barras de rolagem, as cores padrão dos controles de formulário e outros elementos de interface fornecidos pelo navegador, como os sublinhados do corretor ortográfico. <meta name="color-scheme" content="light dark"> no head, colocada antes de qualquer folha de estilo, informa o mesmo ao navegador antes de o CSS chegar; a MDN a recomenda para evitar um flash durante o carregamento da página. Por fim, light-dark(a, b) retorna a primeira cor quando o esquema em uso é claro ou não está definido, e a segunda quando é escuro, sem precisar de media query; a MDN afirma que ela só funciona quando color-scheme tem o valor light dark, geralmente definido em :root.

Por que importa

Uma folha de estilo que apenas escurece os fundos dentro da media query produz uma página escura com inputs nativos brancos, barras de rolagem brancas e um flash branco antes de os estilos serem aplicados. Declarar color-scheme resolve as partes nativas; a media query e light-dark() cuidam das cores do próprio autor.

Como aplicar

• Defina color-scheme: light dark em :root e a meta tag equivalente no head; assim o navegador renderiza corretamente os controles nativos nos dois esquemas.
• Defina a paleta como custom properties em um único lugar, seja com dois blocos (:root { … } @media (prefers-color-scheme: dark) { :root { … } }), seja com light-dark() em cada token.
• Evite preto puro sobre branco puro e vice-versa; reduza a saturação das cores de destaque na paleta escura e verifique o contraste nos dois esquemas, pois uma razão que passa no branco pode falhar no cinza escuro.
• Troque ou recolora as imagens: use <picture> com uma source media="(prefers-color-scheme: dark)" para logotipos e diagramas; SVG inline pode usar currentColor.
• Para um seletor de tema controlado pelo usuário, defina uma classe ou o atributo data-theme em html a partir de um script inline que rode antes da primeira renderização, armazene a escolha e trate "system" como estado padrão.

Armadilhas

Sombras desaparecem em fundos escuros; a elevação precisa ser indicada com superfícies mais claras. PNGs transparentes pressupõem uma página clara. Embeds de terceiros e iframes não herdam a escolha. only light exclui um elemento do esquema do usuário, o que raramente se justifica.

Um seletor de tema também precisa definir color-scheme

Um seletor de tema que apenas troca custom properties deixa os controles nativos no esquema do sistema operacional: página escura, inputs e barras de rolagem claros. Faça o atributo definir também color-scheme:

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

Com isso, os tokens com light-dark() acompanham o seletor automaticamente, porque a função é resolvida a partir do esquema de cores em uso do elemento; uma paleta escrita como dois blocos prefers-color-scheme não faz isso e precisa ter o bloco escuro repetido sob [data-theme="dark"]. Aplique a escolha armazenada a partir de um script inline antes da primeira renderização (com nonce ou hash sob uma Content Security Policy estrita), atualize <meta name="color-scheme"> a partir do mesmo script e mantenha 'system', que não define nenhum atributo, como padrão.