Design Tokens

Design tokens são CSS custom properties nomeadas : valores de cor, tamanhos, qualquer coisa que uma stylesheet possa consumir : armazenados no banco de dados e tornados em declarações :root em cada página construída. Mude o valor do token no admin, reconstrua, e toda regra de stylesheet que referencia aquela variável atualiza no site todo. Nenhuma edição de template, nenhum código.

Esta página explica a tela de Design Tokens, como os tokens alcançam as páginas construídas, e como nomear bem as coisas.

A tela de Design Tokens

Sob Design Tokens na sidebar (Administradores e usuários cujos tipos de conteúdo permitidos incluam design tokens):

A lista mostra cada token ordenado por seu Grupo opcional e depois por nome, cada linha carregando o nome, o valor atual, o rótulo de grupo, e a hora da última atualização.
+ New Token inicia uma entrada fresca.

Criando ou editando um token

Três campos:

Nome : o identificador da variável CSS sem os traços iniciais. Deve começar com uma letra e conter apenas letras, dígitos, hífens e underscores (as regras do CSS rejeitam qualquer outra coisa, incluindo um traço líder). Exemplo: accent-color.
Valor : exatamente o que a variável CSS deveria ser: uma cor (#FAF7F2), um espaçamento (1.25rem), ou até uma referência a outra variável.
Grupo : um rótulo organizacional opcional (colors, mostrado como placeholder); ele ordena a lista, mas é puramente organizacional e não tem efeito sobre o CSS construído.

Regras impostas pelo formulário:

Nomes devem começar com uma letra.
Nomes são únicos no site todo : dois tokens com o mesmo identificador é um erro; edite o existente em vez disso.
Valores existentes permanecem exatamente como estão até você mudá-los (o formulário pré-preenche).

O que um token torna-se no site construído

Em tempo de build, cada token é tornado em uma CSS custom property. Um token nomeado accent-color com o valor #AA2266 torna-se:

:root {
  --accent-color: #AA2266;
}

e aparece no <head> de cada página construída (um único bloco de estilo é adicionado apenas quando ao menos um token existe). A stylesheet do seu tema : ou a stylesheet do tema embutido : referencia-o como var(--accent-color) em qualquer lugar em que aqueles valores sejam usados.

Isto significa:

Para recolorir um tema sem tocar seus templates: crie tokens casando com os nomes de variáveis que a stylesheet dele já usa : você está mudando os valores das custom properties por baixo do design, não as regras de design.
A saída é plenamente qualificada: os valores são strings CSS completas, sem validação, sem coercão de tipo : um token usado como cor só se comporta como cor onde a stylesheet espera uma cor.
Nomes e valores são ambos escapados para HTML na stylesheet emitida, de modo que não há caminho de injeção.

Mudando um token

Edite o valor do token e salve : mas o site não reconstrói por si: tokens não estão amarrados a rebuilds automáticos. Despache um build (dashboard ou agendado) e a próxima passada escreve o novo valor em cada página. Os endpoints de preview partilham a mesma query de token : os previews refletem valores atualizados mesmo enquanto o site ao vivo ainda não foi reconstruído.

Apagando um token

A exclusão é imediata : nenhuma fase de lixeira, nenhuma restauração. No próximo build a CSS custom property simplesmente para de ser emitida. As regras de stylesheet que a referenciavam fazem fallback aos próprios padrões das regras, uma vez que a variável não existe mais nos lugares onde era usada. Se o objetivo era uma mudança de cor, geralmente é melhor atualizar o valor do token existente do que apagar e recriar.

A distinção e o que não confundir

Nomes de token → nomes de variável CSS : sem o traço inicial no ponto de definição; o builder acrescenta o prefixo CSS --.
Rótulos de grupo são para você, não para a stylesheet : ajudam a ordenar a lista, e não mudam o CSS.
Tokens não podem sobregrifar tipos de site. Você não pode fazer um token que não é cor nem comprimento comportar-se como um; tokens são pares nome → valor, nada além de referências CSS.

A versão curta

Defina um nome (uma CSS variable, sem os traços) e um valor na tela de Design Tokens; o build escreve um bloco :root com todos os tokens em cada página : e as stylesheets do tema respondem às referências de variável como cores, espaçamento, ou qualquer outra coisa, sem revisão de template.