Geral

Os tokens aplicam a identidade no dia a dia — fundo, texto, bordas, marca e alertas — com suporte a claro/escuro. São a camada final: o que o componente realmente consome. Existem para que modo claro, modo escuro, marcas e estados de feedback mudem juntos — sem ajustar cor por cor em cada tela.

Não invente variáveis de cor (--ui-custom, hex inline, bg-[#...]). Use os tokens documentados nas famílias abaixo.

Boas Práticas

Quando usar

Definir fundo, texto e bordas com os tokens oficiais das famílias documentadas.

Comunicar sucesso, erro, atenção e informação com os tokens de feedback.

Variantes com transparência (alpha) para overlays, hovers e fundos sutis.

Conferir a família correta antes de passar para o dev.

Quando não usar

Cores digitadas manualmente (`#1052E0`, `rgb(...)`, etc.).

Tons avulsos de paleta quando já existe um token para aquele papel.

Duplicar estilos de modo escuro quando o token já se adapta sozinho.

Criar tokens novos fora do que está documentado aqui.

Famílias de tokens

Família	O que cobre	Página
Marca	Primária e secundária (ações, identidade)	Marca
Feedback	Sucesso, info, atenção, erro	Feedback
Neutro	Token neutro base	Neutro
Texto	Hierarquia tipográfica	Texto
Background	Fundos — página, cards, overlays	Background
Borda	Divisores e contornos	Borda

Regras de aplicação

Cada token tem um papel definido. As cores primitivas (Colors) viram paletas semânticas; os tokens são a camada final — a que se usa de fato na tela. No modo claro, marca e feedback costumam usar tons mais escuros; no escuro, tons mais claros. Cada família mostra exatamente qual referência vale em cada combinação.

Texto: do mais forte (títulos) ao mais suave (legendas e apoio).
Background: do fundo principal ao fundo elevado ou destacado.
Borda: padrão para divisões; versão acentuada quando precisar de mais ênfase.
Marca: primária para ações principais; secundária para apoio visual.

Prefira referenciar o token em vez de repetir a cor. Os componentes do sistema já consomem os tokens por padrão.

Como ler a tabela

Cada célula mostra de onde vem a cor do token. Clique nas referências para ir à paleta primitiva ou semântica correspondente em Colors.

O que aparece	Significado	Exemplo
`UIColors/…`	Tom da paleta base de cores	`UIColors/ME brand/500`
`primary-*`	Cor semântica da marca	`primary-500` → página Primary
`neutral-*`	Cor semântica neutra	`neutral-700` → página Neutral
`alpha/…`	Mesma cor com transparência	`alpha/500-50` → 50% de opacidade
`White / 000000`	Branco ou preto puro	Usado em fundos e contrastes

Tokens em 6 famílias — cada uma com bloco sólido e bloco alpha logo abaixo, quando aplicável.
Paleta completa documentada em Colors e nas páginas de cada família.

Contraste e legibilidade

Os pares de texto e fundo foram pensados para manter leitura confortável nos dois modos. Se combinar tokens de formas diferentes das sugeridas, vale testar se o texto continua fácil de ler.

Texto principal sobre fundo padrão; tons mais suaves sobre fundos mais suaves.
Evitar texto muito fraco onde a pessoa precisa decidir algo importante.
Texto invertido e fundo invertido funcionam como par — use-os juntos.
Alertas de erro e sucesso: escolher texto que contraste bem com o fundo do alerta.

Modo claro e escuro

Modo e tema são duas dimensões independentes — entender a diferença evita retrabalho:

Dimensão	O que muda	Quem controla
Modo (claro ↔ escuro)	Todas as famílias de token	Classe `dark` no `<html>` — gerenciada pelo Nuxt Color Mode
Tema (brand A ↔ brand B)	Só a família Marca (`--ui-primary`)	Configuração do tema ativo no `app.config.ts`

Como funciona na prática: o sistema injeta a classe dark no elemento <html> quando o usuário alterna o modo. Cada token CSS tem dois valores declarados — um para light, outro para dark. O browser resolve o valor certo automaticamente. O dev não escreve nenhuma condicional; o designer não precisa duplicar telas — usar o token já cobre os dois modos.

As tabelas de cada família mostram as colunas Light e Dark exatamente por isso: para deixar explícito qual primitiva o token aponta em cada modo.

Trocar de tema

A troca de tema afeta somente a família Marca. Texto, fundo, bordas e feedback usam a escala neutra — são os mesmos em qualquer tema. Só --ui-primary (e suas variantes alpha) aponta para paletas diferentes conforme a brand configurada.

Configurar o tema correto em app.config.ts antes de implementar.
Verificar que --ui-primary resolve para a paleta esperada no ambiente de destino.
Demais tokens não precisam de atenção ao trocar de tema.

Estados interativos

Hover, foco e pressed devem usar os tokens previstos para isso — variantes com transparência ou tons um degrau mais forte — em vez de inventar opacidade sobre uma cor fixa.

Hover em ação primária: variantes alpha ou tom mais forte da primária.
Anel de foco: variantes alpha mais suaves da primária.
Desabilitado: texto mais fraco sobre fundo mais neutro.
Selecionado / ativo: fundo acentuado com texto em destaque.

Exemplos de uso

Os componentes do sistema já consomem os tokens por padrão. Quando montar algo customizado, prefira referenciar o token em vez de repetir a cor.

<!-- Superfície e texto com tokens -->
<div class="bg-[var(--ui-bg)] text-[var(--ui-text)] border border-[var(--ui-border)]">
  Conteúdo que se adapta ao modo claro/escuro
</div>

<!-- Componentes prontos -->
<UButton color="primary">Salvar</UButton>
<UAlert color="error" title="Falha ao salvar" />

<!-- Fundo sutil para hover ou foco -->
<div class="bg-[var(--ui-primary-25)]">Estado interativo</div>

Veja tambémColors