Como usar tokens semânticos de cor

Sua marca usa verde. O botão principal é verde, a mensagem de sucesso é verde e o item selecionado da navegação é verde. Tudo parece coordenado até a marca mudar para roxo. Uma transferência concluída também deveria ficar roxa? E o contorno de foco ou o aviso ao lado de uma conta prestes a expirar?

Tokens semânticos de cor tornam essas decisões explícitas. Um token primitivo nomeia um valor de cor, como green-700. Um token semântico nomeia sua função, como action-primary-background ou status-success-text. Os componentes fazem referência à função para que uma atualização da marca altere os papéis pretendidos sem mudar acidentalmente todos os usos de um tom parecido.

Comece pelo erro que você quer evitar

Imagine um espaço de trabalho com um botão “Criar projeto”, uma confirmação “Salvo”, uma mensagem de erro e um link selecionado na barra lateral. O designer original escolheu o mesmo verde-escuro para o botão, a confirmação e o link selecionado. Um desenvolvedor, com razão, armazenou esse valor uma única vez e o reutilizou. Agora, uma nova direção de marca pede outra cor principal.

Alterar a variável verde compartilhada atualiza os três elementos. A implementação é consistente com o código original, mas a decisão está errada: a confirmação era verde porque comunica sucesso, não porque representa a ação principal da marca. Essa distinção existia na cabeça do designer e nunca chegou às regras reutilizáveis.

Antes de adicionar tokens, escreva essa distinção em linguagem simples. “A ação principal acompanha a marca do produto. A confirmação de sucesso mantém seu significado de status. A seleção precisa de um estado ativo claro.” Essas frases valem mais do que começar por uma convenção de nomes, porque dizem quais valores podem mudar juntos com segurança.

Como a Atlassian torna a função visível na interface

A orientação de cores da Atlassian relaciona um quadro do Jira a tokens de seleção, texto e fundo de botão da marca. Seu vocabulário distingue funções da cor, ênfase e estado de interação. Também trata seleção e foco de teclado separadamente: um elemento selecionado deve manter seu tratamento de seleção quando um indicador de foco é acrescentado.

Observe por que uma interface anotada é mais útil do que uma paleta sozinha. Uma amostra informa seu valor. O quadro mostra que parte da experiência deve consumir esse valor e por quê. Você consegue verificar se o rótulo se refere a texto, superfície ou ícone, em vez de inferir o uso pretendido pela saturação da cor.

Para um sistema pequeno, adote esse hábito antes de adotar todo o inventário de nomes. Coloque o token proposto ao lado de um uso real, descreva o que provocaria sua mudança e mostre um uso que ele não deve controlar. “Ação da marca” e “operação bem-sucedida” podem começar com o mesmo verde e ainda assim permanecer decisões independentes. Se seu mapa não consegue expressar essa distinção, está armazenando uma paleta, não a semântica da interface.

Torne o teste de dependência concreto

Um pequeno mapa de aliases basta para revelar o erro. Neste mapeamento ilustrativo, o sucesso e a ação principal começam com o mesmo valor, mas fazem referência a funções separadas:

:root {
  --palette-green-700: #236646;
  --palette-purple-700: #6439a8;
  --action-primary-bg: var(--palette-green-700);
  --action-primary-fg: #fff;
  --status-success-text: var(--palette-green-700);
}
[data-brand="purple"] {
  --action-primary-bg: var(--palette-purple-700);
}

Mudar o atributo de marca deve alterar os consumidores de --action-primary-bg. Não deve alterar um rótulo de sucesso que consome --status-success-text. Se os dois mudarem, examine as referências reais dos componentes antes de escolher outro tom. Se nenhum mudar, procure uma cor fixa no código ou uma sobrescrita mais específica. Esse é um teste de dependência; os valores ilustrativos ainda precisam de verificação de contraste em seus contextos reais.

Depois, teste o primeiro plano junto com o fundo. A superfície de uma ação e seu rótulo formam um par. Atualizar apenas a superfície pode tornar ilegível um rótulo antes legível, sobretudo quando uma marca mais clara substitui uma escura. Documente a função associada no mapa para que mudar uma inicie a revisão da outra, em vez de depender da memória de quem revisa.

Verifique a migração em três passagens:

1. Mantenha os valores inalterados. Introduza os aliases e compare com a referência visual. Diferenças inesperadas sugerem erros de mapeamento.
2. Mude temporariamente uma função. Examine todos os consumidores pretendidos, incluindo elementos que devem permanecer inalterados.
3. Restaure o tema aprovado. Revise combinações de passagem do ponteiro, foco, desabilitação e seleção. Registre os valores diretos deliberados separadamente do trabalho de migração inacabado.

Separe valores, funções e decisões de componentes

Um sistema pequeno pode começar com duas camadas. A camada de valores contém as cores reais. A camada de funções mapeia esses valores para finalidades da interface. Uma terceira camada, específica de componentes, é útil quando um componente precisa evoluir de forma independente, mas não é obrigatória para todo projeto pequeno.

Por exemplo, neutral-950 pode conter seu tom neutro mais escuro. Tanto text-primary quanto border-strong poderiam apontar inicialmente para ele. Continuam sendo funções diferentes porque melhorar a legibilidade do corpo de texto não deveria necessariamente escurecer todas as bordas fortes. Valores idênticos hoje não provam que duas decisões devam compartilhar um nome para sempre.

O erro oposto é criar um token exclusivo para cada elemento visível. Se todos os parágrafos comuns cumprem a mesma função, dar a cada um seu próprio token de texto aumenta a manutenção sem acrescentar significado. Uma pergunta útil é: algum dia mudaríamos intencionalmente um desses usos sem mudar o outro? Se sim, considere funções separadas. Se não, reutilize a função existente.

Os nomes devem ajudar a escolher corretamente sem abrir todos os componentes. Um desenvolvedor que procura a borda de erro de um campo não deveria adivinhar se accent-strong, special-red ou brand-secondary significa perigo. Prefira uma função compreensível a uma abreviação engenhosa, sobretudo quando o mesmo contexto será usado por um agente de programação.

Mapeie cores semânticas para funções da interface

Comece examinando uma página representativa em vários estados. Uma captura estática do painel padrão não revelará ações desabilitadas, mensagens de validação, foco de teclado ou um item selecionado de menu. Você precisa de estados suficientes para descobrir funções reais da cor, não de todos os estados teóricos que uma grande organização talvez suporte um dia.

No espaço de trabalho fictício, o primeiro mapa pode cobrir fundo da página, superfície elevada, texto principal, texto secundário, borda comum, ação principal, texto sobre essa ação, seleção, foco, sucesso, aviso e erro. Algumas funções precisam de um par de primeiro plano e fundo. Uma superfície clara de sucesso e seu texto escuro são valores diferentes com um propósito compartilhado.

A primeira revisão é um exercício de mapeamento. Marque cada cor visível na página de exemplo e pergunte o que comunica. Se um painel verde-claro apenas agrupa controles relacionados, pertence a uma função de superfície ou agrupamento. Se anuncia uma operação bem-sucedida, pertence a uma mensagem de retorno. Esses usos podem parecer semelhantes, mas suas mudanças futuras devem seguir regras diferentes.

Mantenha a descrição escrita junto ao nome do token. “Fundo da ação principal: a ação disponível mais importante em uma seção” é mais útil do que apenas “verde”. Inclua um contraexemplo quando houver chance de confusão: o token não significa “qualquer elemento que queremos destacar”. Uma mensagem de erro importante ainda precisa do tratamento adequado de retorno.

Simule uma mudança de marca antes de decidir

Este é um exemplo propositalmente pequeno. O espaço de trabalho começa com a ação da marca verde e as mensagens de sucesso verdes. Depois, a cor da ação muda para outro tom da marca. Você quer que o botão e o tratamento da navegação selecionada acompanhem a nova direção, enquanto “Salvo” mantém sua função reconhecível de sucesso.

Primeiro, identifique as funções afetadas pela decisão de marca. O fundo do botão e seu texto de primeiro plano precisam ser revistos juntos. A seleção pode usar uma superfície ou um indicador separado derivado da marca. O logotipo é um recurso de marca, não um token comum de botão. Não o recolora por uma regra geral de interface sem considerar seus requisitos próprios de recurso.

Depois, mude os mapeamentos de função em uma cópia da página. Não procure todas as ocorrências do hexadecimal antigo para substituí-las indiscriminadamente. Uma busca por valores diretos é útil para encontrar candidatos, mas não revela se uma ocorrência representa um link, um estado de sucesso ou um detalhe de ilustração.

Por fim, examine todos os consumidores das funções alteradas. A ação principal pode aparecer sobre uma página branca, um painel claro e dentro de uma caixa de diálogo. Um novo preenchimento forte em um contexto pode desaparecer em outro. A mudança de mapeamento só está completa quando seus usos pretendidos continuam comunicando a ação correta e permanecem legíveis.

Especifique estados sem criar uma cor para tudo

A aparência padrão de uma ação é apenas parte de seu comportamento. Passagem do ponteiro, pressionamento, foco, seleção e desabilitação podem expressar coisas diferentes. Um item de navegação pode continuar selecionado enquanto recebe foco de teclado. Um botão pode estar em foco sem estar pressionado. Evite reduzir todas essas condições a uma única cor “ativa”.

Comece pela informação que cada estado precisa comunicar. A passagem do ponteiro indica uma relação com o apontador. O foco diz a quem usa teclado onde a interação acontecerá. A seleção identifica uma escolha persistente. Os tratamentos visuais podem compartilhar ingredientes, mas devem continuar distinguíveis quando os estados ocorrerem juntos. Uma borda, sublinhado, ícone ou forma pode transmitir parte da mensagem.

Na barra lateral do exemplo, você poderia usar um fundo sutil de seleção com um contorno claro de foco. O contorno não deve desaparecer só porque o item já está selecionado. Revise diretamente esse estado combinado. Olhar amostras isoladas não mostra se os dois tratamentos interferem um no outro no componente real.

O estilo desabilitado merece o mesmo cuidado. Uma ação desabilitada precisa de explicação quando a pessoa não consegue deduzir por que está indisponível. Tornar um botão cinza não comunica se falta um campo obrigatório, uma permissão ou se uma operação já está em andamento. Um token nomeia uma função visual; não substitui a lógica de interação nem o texto explicativo.

Mantenha visíveis as exceções específicas de componentes. Se uma confirmação destrutiva precisar de um tratamento distinto de botão, documente seu propósito, em vez de substituir silenciosamente o token de ação principal dentro de uma única caixa de diálogo. A exceção pode ser legítima. O problema começa quando ninguém consegue distinguir uma intenção de um atalho pontual de implementação.

Combine cor com significado legível

A cor facilita examinar uma interface, mas o significado precisa sobreviver quando é difícil distinguir o tom. Uma borda vermelha sozinha deixa a pessoa deduzir o que deu errado. Um rótulo de erro e uma mensagem útil de correção tornam o estado compreensível. Da mesma forma, um ícone de sucesso acompanhado de “Alterações salvas” comunica mais do que um ponto verde sem rótulo.

A orientação do W3C sobre o uso de cor explica o requisito de não depender apenas da cor para transmitir informações ou identificar uma ação. Aplique esse princípio a cada função em contexto. Neste espaço de trabalho, mensagens de status recebem texto legível, itens selecionados mantêm um tratamento visível de seleção e links continuam identificáveis além de uma diferença sutil de tom.

Contraste é uma verificação separada. Uma cor pode comunicar o significado correto e ainda ser clara demais para ler. Avalie pares de primeiro plano e fundo, em vez de atribuir um rótulo genérico de “acessível” a uma amostra da marca. Um primeiro plano escuro sobre uma superfície clara de sucesso é uma combinação diferente de texto branco sobre um botão de sucesso saturado.

Para texto normal, o critério de contraste mínimo das WCAG geralmente exige 4.5:1, com 3:1 para texto grande que cumpra as condições e exceções definidas. A explicação do W3C sobre contraste apresenta o escopo e os detalhes. Meça o par real e seu uso renderizado; a aprovação de um par não certifica um componente, tema ou site inteiro.

Os valores anteriores tornam isso concreto. Calcular a luminância relativa do verde #236646 e do roxo #6439a8 resulta em razões de contraste de 6.86:1 e 7.80:1 contra branco. Contra preto, os mesmos preenchimentos resultam em 3.06:1 e 2.69:1. Portanto, ambos suportam o rótulo branco no limite para texto normal, enquanto nenhum suporta o preto nesse limite. O nome semântico não estabelece esse resultado: são os valores específicos de primeiro plano e fundo que o fazem. Mantenha o cálculo associado ao par para que uma futura cor de marca mais clara provoque nova verificação.

Não corrija toda falha escurecendo a interface inteira. Examine qual função falhou, sobre qual superfície e em qual estado. O texto secundário ainda tem uma função de leitura. Uma mensagem auxiliar clara demais não melhora por ser chamada de “sutil”. Por outro lado, transformar todo separador em uma linha escura pesada pode apagar a hierarquia que o sistema deveria criar.

Revise um tema escuro como um novo mapeamento

Um tema escuro é um teste de pressão útil porque separa propósito de aparência. O texto principal ainda precisa ser principal, mas seu valor muda. Uma superfície elevada ainda precisa se distinguir da página. A mensagem de sucesso ainda precisa ser compreensível, mesmo que seus valores de fundo e primeiro plano sejam diferentes dos usados no tema claro.

Não inverta simplesmente cada primitivo nem reutilize os valores do tema claro sobre uma página escura. Reavalie as relações. Uma ação brilhante que parecia equilibrada sobre branco pode dominar uma superfície escura. Uma borda discretamente visível em um painel claro pode desaparecer. Imagens, logotipos e gráficos também podem exigir decisões fora do mapa semântico de cores.

Use o mesmo conteúdo nas duas prévias de tema. Caso contrário, diferenças de densidade ou imagens podem desviar a atenção das decisões de cor. Inclua um erro de formulário, uma mensagem de sucesso, um item selecionado de navegação, um controle em foco e algum texto secundário. Esses estados criam uma comparação mais útil do que uma galeria de botões padrão atraentes.

Os nomes das funções devem permanecer estáveis na comparação. Se você estiver renomeando text-primary para white-text no tema escuro, estará devolvendo um valor a um nome que deveria descrever uma função. Mantenha o significado constante e mude o mapeamento que o atende.

Dê ao agente de programação o mapa, além da paleta

Ao pedir a um agente que refine uma página, inclua as decisões de função junto da referência visual. Uma captura mostra as cores atuais. Não explica quais devem continuar vinculadas durante uma mudança de marca nem quais combinações de estado precisam continuar funcionando. Uma pequena tabela de mapeamento e um componente representativo tornam essa intenção muito mais fácil de examinar.

Nas prévias HTML compatíveis do OpenDesign, você pode revisar o resultado renderizado, usar os controles disponíveis de edição manual de estilo e anexar comentários à área relevante para a conversa. Use esses recursos para apontar uma divergência concreta, como uma mensagem de sucesso usando o tratamento da ação principal. O comentário deve nomear a função pretendida e a localização visível.

Por exemplo, peça ao agente para atualizar o mapeamento da ação principal, preservando as funções de sucesso e erro, e depois mostrar os usos afetados de botão em seus diferentes estados. Se seu projeto já tiver convenções de tokens, forneça esses arquivos ou o contexto do design. Evite pedir um sistema inteiramente novo de nomes como parte de uma pequena correção de cor.

Depois de uma correção visual, examine a referência do componente nos arquivos gerados. O botão pode parecer correto e ainda consumir o token de sucesso; a próxima mudança de tema revelaria o mesmo erro de dependência.

Migre primeiro um componente representativo

Você pode introduzir funções semânticas sem substituir o site inteiro de uma só vez. Escolha um componente com vários estados significativos, como o formulário de criação de projeto. Liste seus valores atuais, decida a função de cada um e mapeie essas funções para a paleta existente. Inicialmente, o design visível pode permanecer quase inalterado.

Depois, mude um mapeamento de função como teste controlado. Se ações principais devem mudar juntas, verifique se os botões pretendidos mudam. Se mensagens de status devem permanecer independentes, verifique se não acompanham a cor da ação. O teste é sobre a dependência, não sobre a qualidade da cor temporária como escolha final da marca.

Mantenha um registro dos consumidores que ainda usam valores diretos. Alguns serão deliberados: uma ilustração, um logotipo de parceiro ou uma visualização de dados pode não pertencer à mesma função de interface. Outros são trabalho de migração. Identifique a distinção para que a próxima pessoa não confunda uma conversão incompleta com uma exceção aprovada.

Quando o componente representativo se comportar corretamente, expanda para os componentes relacionados. Revise a página renderizada depois de cada grupo significativo, em vez de confiar em uma substituição global. Regras compartilhadas podem afetar contextos que não estavam abertos. Uma migração pequena dá a chance de encontrar esses contextos antes que a comparação da interface inteira se torne mais difícil.

O que uma revisão útil de tokens deve deixar

A revisão final deve deixar um mapa utilizável por outra pessoa: nomes das funções, seus propósitos, valores atuais por tema compatível e alguns componentes representativos mostrando seu comportamento. Acrescente notas quando uma função precisar ser associada a outra, como texto sobre o fundo de uma ação. Registre exceções importantes sem transformar cada pixel em uma política separada.

Peça a um colega que escolha, com esse mapa, o token para uma nova mensagem de sucesso e para uma nova ação principal. Se ele escolher corretamente sem adivinhar pelas amostras, o sistema está fazendo um trabalho útil. Se ambas as escolhas ainda levarem a “use o verde da marca”, esclareça as descrições das funções antes de adicionar mais tokens.