Cor: cada pigmento tem uma função.
Claro, névoa, pistache, escuro, verde e imagem resolvem o mesmo contrato em seis condições de luz. A cor organiza plano, leitura, limite, ação e estado; a identidade não depende de um único fundo escuro.
Seis papéis no mesmo plano.
A amostra separa o fundo do ambiente, o material do componente e o campo de ação. O estado de erro mantém texto explícito e limite funcional, sem depender apenas da percepção da cor.
-
Fundo do ambiente
--xq-fundo define a base opaca. O tema imagem também oferece um plano sólido; texto não depende da região clara ou escura de uma fotografia.
-
Superfície do componente
--xq-superficie e --xq-superficie-alt estabelecem planos locais. Um data-tema aninhado recalcula os aliases sem herdar cores já resolvidas do tema externo.
-
Texto e apoio
O título usa --xq-texto. Metadados e ajuda usam --xq-texto-suave, com contraste de leitura medido no plano em que aparecem.
-
Erro com texto
O perigo muda limite e mensagem. A frase identifica o problema; cor sozinha não informa o que aconteceu nem como prosseguir.
-
Anel de foco
O foco é um par: separador interno na cor do fundo e anel externo no sinal do tema. A ação continua reconhecível sobre material claro ou escuro.
-
Par da ação
--xq-realce e --xq-sobre-realce formam um par. O acento sólido possui aliases próprios, incluindo a proteção contra laranja sólido sobre verde sólido.
Contratos de tokens CSS
Valor ou alias no tema claro, propriedade consumidora e limite de uso. Cores são apresentadas em RGB equivalente; a fonte continua no CSS de tokens. O inspetor mostra a resolução no tema escolhido.
| Token / expressão | Aplicação CSS | Regra |
|---|---|---|
--xq-fundo
rgb(244 243 237)
|
[data-tema]
background-color
|
Base opaca em todos os seis temas; o tema imagem não exige fotografia para legibilidade. |
--xq-superficie
rgb(231 231 222)
|
.xq-icone-botao
background
|
Material local; não substituir por transparência arbitrária. |
--xq-superficie-alt
rgb(252 252 247)
|
.xq-input[readonly]
background
|
Plano alternativo do campo somente leitura; o campo editável padrão usa --xq-fundo. Estados disabled também adotam o plano alternativo. |
--xq-texto
rgb(25 39 32)
|
.xq-icone-botao
color
|
Leitura principal; texto normal requer ao menos 4,5:1 sobre seu plano. |
--xq-texto-suave
rgb(70 89 79)
|
.xq-nota
color
|
Ajuda e legendas continuam com contraste de texto, mesmo sendo secundárias. |
--xq-linha-forte
rgb(97 115 104)
|
.xq-icone-botao
border-color
|
Limite funcional com critério de interface; não trocar pela linha decorativa. |
--xq-realce
rgb(36 71 53)
|
.xq-btn
background / border-color
|
Usar junto de --xq-sobre-realce; o par muda por tema. |
--xq-sobre-realce
rgb(247 248 242)
|
.xq-btn
color
|
Texto da ação preenchida; não manter branco fixo nos seis temas. |
--xq-acento-solido
var(--xq-acento)
|
.xq-btn--acento
background / border-color
|
Alias seguro: neutro no pistache e lima no verde; evita laranja sólido tocando verde sólido. |
--xq-focus-inner
var(--xq-fundo)
|
.xq-icone-botao:focus-visible
box-shadow
|
Separação interna na cor local do fundo; preservar antes do anel externo. |
--xq-focus-outer
var(--xq-anel)
|
.xq-icone-botao:focus-visible
outline-color
|
Anel externo; não depender só da mudança de preenchimento. |
--xq-perigo
rgb(146 60 67)
|
.xq-input[aria-invalid="true"]
border-color
|
Erro de campo precisa também de aria-invalid e mensagem associada. |
Uso correto × uso incorreto
Compare a mesma intenção em duas composições. Os exemplos são amostras de leitura; os controles operáveis ficam no playground.
Uma função por sinal.
Leitura, ação e erro mantêm papéis distintos no mesmo tema.
Erro: preencha o nome da loja antes de continuar.
- Texto e plano resolvem dentro do mesmo tema, com pares cromáticos próprios.
- As ações principal e secundária mantêm preenchimentos diferentes e destinos reais.
- A mensagem de erro usa o papel --xq-perigo e descreve o campo que precisa de atenção.
Uma função por sinal.
Ação, estado e informação recebem o mesmo tratamento.
Consultar a fundaçãoVer tipografiaErro: nome da loja ausente- Ação, informação e erro aparecem como selos idênticos.
- O mesmo sinal visual oculta a prioridade entre consultar e complementar a leitura.
- O erro tem texto, mas seu tratamento não o distingue das opções vizinhas.
Bancada de temas e estados.
Mude o tema local para comparar os mesmos papéis. Estados preservam a mensagem em palavras; o valor demonstrativo conta o conjunto de seis atmosferas, sem simular medição automática de contraste.
O mesmo contrato.
Seis atmosferas.
Cor local pronta: leitura, ação e limite usam o mesmo tema.
- Texto de apoio
- Papel suave, contraste de leitura.
- Erro demonstrativo
- Informe o nome da loja para prosseguir.
Pronto. Altere um controle para inspecionar o contrato.
Ensaio local e determinístico. A ação percorre carregamento → sucesso; movimento reduzido entrega o estado final imediatamente. Repetir preserva os controles.
Inspecionar tokens resolvidos
--xq-fundo- rgb(244 243 237)
--xq-superficie- rgb(231 231 222)
--xq-superficie-alt- rgb(252 252 247)
--xq-texto- rgb(25 39 32)
--xq-texto-suave- rgb(70 89 79)
--xq-linha-forte- rgb(97 115 104)
--xq-realce- rgb(36 71 53)
--xq-sobre-realce- rgb(247 248 242)
--xq-acento-solido- var(--xq-acento)
--xq-focus-inner- var(--xq-fundo)
--xq-focus-outer- var(--xq-anel)
--xq-perigo- rgb(146 60 67)
Aplicar o contrato
Encapsular um tema local
A regra [data-tema] resolve os aliases no escopo em que o componente aparece. Evite definir apenas a cor do texto.
<section class="xq-moldura" data-tema="escuro">
<h2>Plano de leitura opaco.</h2>
<p class="xq-nota">Ajuda e contexto no mesmo ambiente.</p>
<a class="xq-btn" href="fundamentos.html">Consultar a fundação</a>
</section>Manter os pares cromáticos
Uma variante nova deve preservar texto, preenchimento e foco em cada tema. Não fixe um pigmento de marca no componente.
.acao-local {
background: var(--xq-realce);
color: var(--xq-sobre-realce);
border: 1px solid var(--xq-realce);
}
.acao-local:focus-visible {
outline: var(--xq-focus-width) solid var(--xq-focus-outer);
outline-offset: var(--xq-focus-gap);
box-shadow: 0 0 0 var(--xq-focus-gap) var(--xq-focus-inner);
}Associar erro e campo
A cor reforça o erro. aria-invalid anuncia o estado e aria-describedby liga o campo à frase que identifica o problema. O exemplo é marcação; a validação pertence ao comportamento do formulário.
<div class="xq-campo">
<label for="nome-loja">Nome da loja</label>
<input class="xq-input" id="nome-loja" name="loja"
aria-invalid="true" aria-describedby="nome-loja-erro">
<p class="xq-campo-erro" id="nome-loja-erro">
Preencha o nome da loja antes de continuar.
</p>
</div>Critérios de aceite
- Texto e placeholders mantêm 4,5:1 no plano real, em cada tema.
- Foco e limite funcional mantêm 3:1; hairline decorativa não substitui esse limite.
- Estado de erro possui mensagem textual, sem depender exclusivamente da cor.
- Pistache e verde usam o alias de acento sólido, sem contato laranja sólido × verde sólido.