Gere a meta tag color-scheme e a propriedade CSS

Escolha claro quando a página aceitar somente uma interface clara, escuro quando aceitar apenas uma interface escura ou ambos quando todos os componentes tiverem sido preparados para as duas aparências. O resultado é determinístico, normalizado e adequado para templates, folhas de estilo, sites estáticos, bibliotecas de componentes e pipelines de build.

Declare os esquemas realmente aceitos pela interface

A declaração color-scheme é uma promessa sobre a página, não um conversor automático de temas. Selecione claro somente quando controles, fundos, textos, bordas, imagens e estados de foco funcionarem em uma apresentação clara. Selecione escuro quando esses elementos tiverem sido preparados para a apresentação escura. Escolha ambos quando a interface inteira funcionar nos dois esquemas. O gerador converte essa opção no valor ordenado <code>light dark</code>, indicando preferência pelo claro. A exatidão importa porque o navegador pode usar a informação em controles nativos, barras de rolagem e no fundo do documento. Uma declaração ampla demais pode criar controles incompatíveis ou flashes ilegíveis. Antes de copiar, revise campos desabilitados, preenchimento automático, validação, seleção de texto, blocos de código, widgets e ícones. O melhor valor é a descrição mais restrita e verdadeira do suporte publicado. A ferramenta formata essa descrição; o design e os testes confirmam se ela corresponde à realidade.

Posicione o HTML e o CSS gerados corretamente

Coloque o elemento meta no <code>&lt;head&gt;</code> do documento, de preferência antes que o navegador pinte partes importantes da interface. A tag retornada está completa e pode ser inserida em HTML estático, layout renderizado no servidor ou configuração de cabeçalho de um gerador de sites. Coloque a declaração CSS na regra que represente o escopo desejado. Para o documento inteiro, normalmente será <code>:root</code>; um componente pode aplicá-la à própria raiz. O gerador devolve a declaração sem seletor para permitir uso em CSS comum, preprocessadores, módulos CSS e objetos de estilo. As duas saídas compartilham o mesmo valor normalizado, evitando divergências entre metadados e estilos. Você pode usá-las juntas como dica antecipada e valor explícito da cascata, ou integrar apenas a saída necessária. Depois, inspecione o código renderizado e o CSS compilado, pois frameworks, gerenciadores de cabeçalho, minificadores e declarações duplicadas podem mudar o valor efetivamente recebido pelo navegador.

Separe o suporte da escolha do tema

Aceitar dois esquemas e selecionar o tema ativo são tarefas relacionadas, mas diferentes. <code>light dark</code> informa que as duas apresentações são aceitas; não cria tokens de cor, seletor de tema, preferência persistente nem consultas de mídia. Uma implementação robusta define variáveis semânticas para superfícies, texto, bordas e destaques e muda essas variáveis conforme a estratégia do produto. Ela pode seguir a preferência do sistema, respeitar uma opção da conta, reagir a um atributo do documento ou combinar abordagens. Gere a declaração somente depois de concluir os estados visuais. Teste a página com sistemas claros e escuros, navegação por teclado, zoom e modos de alto contraste ou cores forçadas. Confira imagens, iframes, formulários externos, realce de sintaxe e diálogos nativos. Na automação, armazene a entrada escolhida junto das strings geradas. Se um tema deixar de ser aceito, gere novamente as duas declarações pela nova escolha, sem editar apenas uma. Uma única fonte impede divergências entre templates, pacotes e implantações.