Um token de cor bruta nomeia a própria cor: --blue-500, --gray-900. Um token semântico nomeia o trabalho que a cor realiza: --primary, --background, --muted-foreground. Os componentes podem, então, ignorar os matizes literais da marca. Um botão estilizado com bg-primary text-primary-foreground funciona com verde sálvia, rosa choque ou um tema escuro porque a função permanece fixa enquanto seu valor muda.

Este é o modelo que o shadcn/ui popularizou e sobre o qual a tematização do Tailwind é construída. Com tokens semânticos, a re-tematização de um app pode ser limitada a um único bloco :root. Classes fixas como bg-gray-900 e text-white transformam essa mesma mudança em uma busca por todo o código.

A maioria das funções base vem com uma função -foreground pareada para texto ou ícones naquela superfície: --primary / --primary-foreground, --card / --card-foreground, --muted / --muted-foreground. Use --primary-foreground sobre --primary em vez de esperar que o foreground padrão tenha contraste suficiente. Cada par ainda deve ser verificado em ambos os modos.

Uma paleta mínima de três cores deixa 25 decisões indefinidas: estados de hover, texto suave, bordas, anéis de foco, séries de gráficos, modo escuro. Um sistema completo nomeia todas elas. Os kits do Identity Forge definem essas 28 funções, agrupadas pelo que fazem, para os modos claro e escuro:

• Superfícies: background / foreground, card / card-foreground, popover / popover-foreground. A página, painéis elevados e camadas flutuantes, cada uma com sua cor de texto legível.
• Marca e ênfase: primary / primary-foreground, secondary / secondary-foreground, accent / accent-foreground. A ação principal, a de suporte e o destaque.
• Suave e neutro: muted / muted-foreground. Fundos suaves e texto secundário.
• Estado: destructive / destructive-foreground, success / success-foreground, warning / warning-foreground. Erros, confirmações e avisos.
• Formulário e foco: border, input, ring. Divisores e contornos, superfícies de campos de formulário e o indicador de foco.
• Dados: chart-1, chart-2, chart-3, chart-4, chart-5. Cinco cores de série distintas e alinhadas à marca para que os gráficos não recorram a uma paleta padrão genérica.

Abaixo está o kit gratuito ambient-sage renderizado inteiramente a partir desses tokens. A linha de amostras é --primary, --secondary, --accent e as cinco funções de gráfico; o botão usa --primary com --primary-foreground; as superfícies usam --background, --card e --muted. Nada aqui é uma cor fixa:

Você pode definir todas as 28 funções manualmente, mas é tedioso manter o equilíbrio e a acessibilidade entre os modos claro e escuro. Cada kit do Identity Forge já as envia completas em ambos os modos, exportáveis como variáveis CSS, Tailwind v3/v4 @theme, um item de registro shadcn ou DTCG/W3C JSON. A maneira mais rápida de inserir um conjunto completo em um projeto shadcn/ui:

npx shadcn add https://identityforge.io/r/ambient-sage.json

Os tokens também são metade de um DESIGN.md: os valores que o briefing escrito referencia. Juntos, eles são o que você fornece a um agente de codificação para que a UI dele permaneça coerente.