Cor semântica vs. cor bruta
Um token de cor bruta nomeia a própria cor: --blue-500, --gray-900. Um token semântico nomeia a função que a cor desempenha: --primary, --background, --muted-foreground. Assim, os componentes podem ignorar as matizes literais da marca. Um botão estilizado com bg-primary text-primary-foreground funciona com verde-sálvia, rosa choque ou em um tema escuro, pois a função permanece fixa enquanto seu valor muda.
Este é o modelo que o shadcn/ui popularizou e no qual a tematização do Tailwind se baseia. Com tokens semânticos, a re-tematização de um app pode ser limitada a um único bloco :root. Classes hardcoded, como bg-gray-900 e text-white, transformam a mesma alteração em uma busca por todo o codebase.
A regra de pareamento de foreground
A maioria das funções base vem com uma função -foreground pareada para textos ou ícones naquela superfície: --primary / --primary-foreground, --card / --card-foreground, --muted / --muted-foreground. Use --primary-foreground sobre --primary em vez de torcer para que o foreground padrão tenha contraste suficiente. Cada par ainda deve ser verificado em ambos os modos.
As 28 funções que um sistema completo precisa
Uma paleta mínima de três cores deixa 25 decisões indefinidas: estados de hover, texto muted, 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 por finalidade, 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 um 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. - Sutis e neutros:
muted/muted-foreground. Planos de fundo discretos e texto secundário. - Estado:
destructive/destructive-foreground,success/success-foreground,warning/warning-foreground. Erros, confirmações e alertas. - 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.
Por que cinco cores de gráfico são importantes
A visualização de dados é onde sistemas subespecificados falham mais visivelmente: um dashboard com três cores de marca e um arco-íris aleatório em seu gráfico de barras. Definir de chart-1 a chart-5 antecipadamente mantém os gráficos dentro da mesma linguagem visual do restante do app.
Veja as funções em um kit real
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 hardcoded:
Ambient Sage
Live renderRendered from the kit's actual tokens, fonts, and treatments
Typography
Plus Jakarta Sans
Color system
28 semantic roles, light + dark
Agent outputs
DESIGN.md, CSS, Tailwind, shadcn
Obtenha um conjunto completo de tokens
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 as entrega completas em ambos os modos, exportáveis como variáveis CSS, @theme do Tailwind v3/v4, um item de registro do shadcn ou JSON DTCG/W3C. A maneira mais rápida de adicionar um conjunto completo a um projeto shadcn/ui:
npx shadcn add https://identityforge.io/r/ambient-sage.jsonOs tokens também compõem metade de um DESIGN.md: os valores aos quais o brief escrito faz referência. Juntos, eles são o que você fornece a um agente de código para que a UI permaneça coerente.
FAQ
O que são design tokens de cores semânticas?
Variáveis de cor nomeadas por função em vez de matiz: --primary, --background, --muted-foreground em vez de --blue-500. Os componentes são estilizados com base no nome da função, portanto, alterar temas ou mudar para o modo escuro nunca exige a edição de componentes.
De quantos tokens de cores um design system precisa?
O Identity Forge utiliza 28 funções semânticas: superfícies com seus respectivos foregrounds, funções de marca e muted, cores de estado, funções de formulário e cinco cores de gráfico. Cada função possui um valor para o modo claro e outro para o escuro.
O que é a convenção -foreground?
A maioria das roles base é combinada com uma role -foreground para o texto ou ícones posicionados sobre aquela superfície: --primary com --primary-foreground. Esse pareamento garante contraste legível tanto no modo claro quanto no escuro, sem a necessidade de suposições.
Como exporto um conjunto completo de tokens semânticos?
Cada kit do Identity Forge exporta suas 28 roles (light + dark) como variáveis CSS, @theme do Tailwind v3/v4, um item de registro do shadcn ou JSON DTCG/W3C. Para shadcn/ui, o comando npx shadcn add https://identityforge.io/r/<slug>.json as instala diretamente.