Tokens semânticos e primitivos
Um token semântico é um token de design nomeado pela função que cumpre e não pelo valor que carrega, como --color-text-danger em vez de --color-red-600. Em geral ele referencia um token primitivo, o que permite mudar o valor subjacente sem renomear nada que o utilize.
As duas camadas
A maioria dos sistemas de tokens maduros tem pelo menos dois níveis.
Tokens primitivos (também chamados de crus, globais ou de núcleo) guardam os valores reais. São nomeados de forma descritiva:
--red-600: #DC2626;
--blue-500: #2563EB;
--space-4: 16px;Tokens semânticos guardam decisões sobre onde esses valores são usados. São nomeados pelo papel:
--color-text-danger: var(--red-600);
--color-action-primary: var(--blue-500);
--space-card-padding: var(--space-4);Componentes referenciam a camada semântica. Quase nada deveria referenciar um primitivo diretamente.
Por que a indireção compensa
Rebranding deixa de ser uma reescrita. Mude para onde --color-action-primary aponta e todos os botões acompanham. Se os componentes referenciassem --blue-500, você teria de editar cada componente, e os que usavam azul por um motivo alheio a ações quebrariam.
Temas passam a ser possíveis. O modo escuro são os mesmos nomes semânticos apontando para primitivos diferentes. Sem a camada semântica não há nada para reapontar.
O código diz o que significa. --color-text-danger explica a quem lê por que aquele valor está ali. --red-600 não diz nada, o que pesa principalmente quando alguém precisa decidir se mudá-lo é seguro.
O erro comum
Times pulam a camada semântica porque no primeiro dia ela parece burocracia: há onze cores e todo mundo lembra para que servem.
O custo aparece no primeiro rebranding, no primeiro modo escuro ou na primeira revisão de acessibilidade, e a essa altura os primitivos estão referenciados em centenas de lugares. Adicionar uma camada semântica depois é um trabalho mecânico, porém tedioso, que ninguém agenda.
Um terceiro nível
Sistemas maiores acrescentam tokens no nível do componente: --button-primary-background apontando para --color-action-primary apontando para --blue-500.
Ajuda quando um componente realmente precisa divergir, e custa indireção quando não precisa. Dois níveis é o padrão certo; acrescente o terceiro quando surgir um caso real, não por antecipação.
Onde o Flash DSM entra
Sistemas gerados já vêm com os dois níveis prontos: escalas primitivas e papéis semânticos para texto, fundo, borda e estados que as referenciam, em claro e em escuro.