DSvault

Carregando...

Registrar

Design System - Design Tokens - DesignSystemOps - 20/04/2022

Automatizando o handoff de Design Tokens

Compartilhe por ai!

Como utilizar o Figma e o Style Dictionary para automatizar o handoff de Design Tokens

 

Automatizando o Handoff de Design Tokens

 

Já faz um tempo que estudo sobre design tokens e como trabalhá-los da melhor forma, para diminuir as inconsistências, ganhar escalabilidade e automatizar o handoff entre design e front-end. Esse artigo acaba sendo complementar ao artigo escrito pelo @sergio (inclusive, uma leitura mais lógica começaria por aqui e terminaria lá).

 

Meu objetivo aqui é mostrar como estruturar seus tokens no Figma para convertê-los no Style Dictionary. Então nosso roadmap vai ser basicamente este:

 

Roadmap de exportação de Design Tokens

Roadmap de exportação de Design Tokens

 

 

  1. Designers definem os tokens no Figma
  2. Importam esses tokens para o plugin Figma Tokens
  3. Ao mesmo passo que exportam os estilos do plugin para o Figma, geram um arquivo JSON
  4. O arquivo JSON é sincronizado e armazenado em um repositório Github.
  5. Por sua vez, desenvolvedores utilizam o pacote Style Dictionary para fazer a conversão de tokens
  6. Disponibilizam um pacote NPM com os tokens convertidos

E quais são os ganhos disso?

 

Além de possuir design tokens sincronizados entre o seu time de design e front, facilita (e muito!!! 🙏) a conversão desses tokens para formatos variados. No final disso tudo, os desenvolvedores vão poder utilizar os tokens convertidos por meio da instalação do pacote NPM e, toda vez que esse pacote for atualizado, ele deve refletir em todos os projetos.

Espera aí então, Ana. Quer dizer que quando eu fizer as alterações no figma vai refletir no front?

 

Exatamente! Mas pra gente chegar lá, tem muito asfalto pelo caminho.

Por que a escolha do Style Dictionary?

 

Confesso que já testei um pouquinho de tudo.

 

No Houston, o Design System do cVortex, utilizamos o Figmagic para exportar os design tokens do Figma e convertê-los. Apesar de ser uma alternativa prática, ainda tem suas limitações. Testei também o conversor Theo, desenvolvido pela Salesforce, que é poderosíssimo, mas não chegou aos pés do Style Dictionary, densenvolvido pela Amazon, que permite uma flexibilidade incrível de configurações.

 

O Style Dictionary consegue converter arquivos JSONC, JSON5, JS, YAML em vários formatos, reorganizando os tokens em diretórios pré-configurados, facilitando o uso deles em diversos tipos de aplicações.

 

Convertendo design tokens exportados do Figma para vários formatos

Convertendo design tokens exportados do Figma para vários formatos

 

 


 

 

Pra facilitar a navegação nesse artigo que mais parece um e-book:

 

 


Como o Style Dictionary interpreta um arquivo

 

Em sua documentação, o Style Dictionary deixa claro como os arquivos são interpretados e traduzidos para as suas propriedades. Apesar dele deixar sinalizado que esta estrutura é flexível, preciso explicar como isso impacta no output do seu projeto.

 

Modelo estrural proposto pelo Style Dictionary

Modelo estrural proposto pelo Style Dictionary

 

 

Basicamente, o modelo estrutural acima, equivale a um JSON estruturado da seguinte forma:

/* tokens.json */ {
    "color": {
        "background": {
            "button": {
                "primary": {
                    "active": {
                        "value": "{color.primary.active}",
                        "type": "color"
                    }
                }
            }
        }
    }
}/

 

As suas propriedades seriam traduzidas para:

token.attribute.category = color
token.attribute.type = background
token.attribute.item = button
token.attribute.subitem = primary
token.attribute.state= active
token.value= {brandname.color.primary.active}
token.type= color

 

Quando convertido, o resultado final seria (utilizando CSS como exemplo):

:root {
--color-background-button-primary-active: var(--color-primary-active);
}

Entendido isso, precisamos entender como o Figma Tokens gera o JSON.


Antes de mais nada, vamos alocar os estilos no plugin

 

Como organizar seus arquivos no Figma

 

A primeira coisa que a gente tem que fazer é bolar uma estratégia de organização dos nossos arquivos no Figma. Pra isso, precisamos primeiro definir quais bibliotecas de design tokens iremos criar.

 

No meu caso irei fazer dois temas: claro e escuro. Para isso vou criar dois arquivos diferentes no Figma para vincular os estilos como se fossem temas. Essa estratégia possibilita que eu alterne entre temas sem o uso de um plugin (sinalizando a biblioteca de estilo dentro do próprio Figma). Mas se preferir, recomendo o plugin Themer para fazer essa alternância, puxando os dados de json armazenados no jsonbin.io.

 

Arquivos Design Tokens Figma

Arquivos Design Tokens Figma

 

No Figma Tokens, eu vou criar três sets diferentes: o “global”, que vai conter todos os meus tokens de base, o “light” que irá conter todos os meus aliases tokens e components tokens do tema claro e o “dark” que irá conter todos os aliases tokens e components tokens do tema escuro.

 

💡Macetizinho: crie primeiro o tema light. Depois de pronto, copie seu JSON para o set “dark” e altere os valroes (não as chaves!!!!)

 

 

 

 

Existem três formas levar seus estilos para o plugin Figma Tokens: importando os estilos já criados no Figma, importando de um JSON existente, criando manualmente um por um. Existem vantagens e desvantagens em cada um:

  • Quando você importa estilos já criados no Figma, acaba sendo uma ação massificada, porém, em seguida, pode exigir muito tempo em ajustes de categorias, nomenclaturas e apontamentos de aliases;
  • Importar de arquivos JSON pode ser vantajoso se ele estiver no formato que o Figma Tokens consegue ler, senão… Haja trabalho! 😰
  • Não preciso nem explicar quão verboso pode ser fazer manualmente no plugin já que, além de ter que cadastrar um por um, depois você precisa atualizar todos os elementos que vão consumir esses tokens 😭. Mas o lado positivo é que você não vai quebrar a cabeça para organizar e gerar seu arquivo JSON.

 

 

Mas vou tentar facilitar a sua vida com algumas dicas:

 

👉 Importando estilos do Figma

 

Eu uso algumas estruturas semânticas para nomear meus estilos no Figma e torná-los fácil de organizar tanto na plataforma quanto no Style Dictionary.

 

Para tokens de fundação e aliases, a estrutura que uso é:

categoria/propriedade/escala-estado

Dessa forma, tenho tokens com as nomenclaturas: color-fuji-bright e color-background-light

 

Para components tokens, a estrutura começa com:

component/nomedoComponente/elemento/categoria/propriedade/escala-estado-modificador

O resultado seriam tokens como component-button-shape-color-background-primary

 

Não se amarre a todos esses níveis semânticos. Essa estrutura acaba sendo bastante dinâmica, já que cada token pode trazer atributos diferentes. A / é responsável por indicar uma pasta, enquanto o -  é um elemento da convenção kebab para separar as palavras.

Particularmente eu gosto bastante de usar kebab para nomear tokens, por facilitar a leitura, mas vocês podem escolher a convenção mais interessante para o cenário que vivem.

 

Quando os estilos nessa estrutura são importados para o Figma Tokens, a estrutura de pasta é respeitada. Lembre-se de, antes de iniciar a importação, selecionar o set para o qual os tokens serão importados, e em seguida selecionar somente aqueles que fazem parte do set.

👉 Importando do JSON

 

Para o arquivo JSON funcionar no Figma Tokens, existem algumas coisas que você precisa saber.

Primeiro: o Figma Tokens consome a API do Figma
Segundo: Nem todo tipo de Token está disponível (infelizmente alguns deles vocês vão ter que inserir manualmente, inclusive recomendo um arquivo JSON apartado para isso), mas você pode ver a lista aqui.

 

Um arquivo razoável de JSON segue esta estrutura:


{
    "color": {
        "background": {
            "button": {
                "primary": {
                    "active": {
                        "value": "{color.primary.active}",
                        "type": "color"
                    }
                }
            }
        }
    }
}

 

É importante saber que "type"="color" vai determinar a sessão em que o token vai aparecer no plugin. "color", "background" , "button"e "primary" vão se transformar em uma árvore, onde “color” é a categoria principal. "active", por sua vez, será a propriedade.

 

Quando se trata do token.type, já existem alguns tipos pré-definidos para o Figma Tokens:

 

"borderRadius" – tokens do tipo raio da borda
"borderWidth" – tokens do tipo espessura da borda
"boxShadow" – tokens do tipo sombra
"color" – tokens do tipo cor
"fontFamily" – tokens do tipo família tipográfica
"fontSizes" – tokens do tipo tamanho de fonte
"fontWeights" – tokens do tipo espessura da fonte
"lineHeights"– tokens do tipo altura da linha
"letterSpacing" – tokens do tipo espaçamento de letras
"paragraphSpacing" – tokens do tipo espaçamento do parágrafo
"opacity" – tokens do tipo opacidade
"sizing" – tokens do tipo tamanho
"spacing" – tokens do tipo espaçamento
"others" – tokens que não se encaixam nas modalidades acima

 

 

👉Inserindo tokens diretamente no plugin

 

 

 

 

💡 Importantíssimo: tenha como prioridade o uso dos estilos gerados para o Figma nos seus componentes e elementos visuais. Do plugin você vai utilizar somente aqueles tokens que o Figma não salva como estilo (como border radius, border width, etc…). Mesmo quando você atualizar valores no plugin, os estilos do Figma vão ser refletidos e daí basta publicar a biblioteca onde você armazenou estes estilos pra galera ter acesso!

 

Ok designer, se você chegou até aqui, está na hora de respirar! As coisas vão ficar cada vez mais densas agora e é uma boa ideia que, a partir daqui, o seu desenvolvedor também realize esta leitura.

 


Hora de sincronizar!

 

Chegou a hora mais importante: a sincronização. É ela quem vai permitir a “conversa” entre design e front.

 

Se você já tem uma conta no Github (futuramente o Figma Tokens vai permitir a sincronização com o Bitbucket também), crie um novo repositório que armazenará os seus tokens. Você vai precisar criar um token de acesso pessoal para permitir que o Figma acesse o repositório. A sugestão aqui é que você coloque o vencimento indefinido para não ter que configurar o Figma Tokens toda vez que expirar. Marque também a opção “repo” e gere o seu token. Lembre-se de copiá-lo e guardá-lo em um lugar seguro.

 

Criando um token pessoal no github

Criando um token pessoal no github

 

 

Em seguida, abra o Plugin Figma Tokens e navegue para a aba “Sync”. Escolha a opção “GitHub” e configure-o de acordo com com os dados do seu repositório.

 

Configurando Sync com Github

Configurando Sync com Github

 

Name: É o nome dessa configuração de sincronização. Você pode colocar, por exemplo “Git Light Theme” se for trabalhar com multiplos arquivos

Personal Acess Token: É o token gerado no github

Repository: sempre tem que seguir o fomato usuario/nomedorepositorio

Default branch: normalmente é a main, mas se a raiz principal do seu repositório tiver outro nome, indique-o aqui

File Path: o nome do arquivo que conterá os seus tokens (lembra que eu falei que todos os sets seriam agrupados em um arquivo só?)

 

 

Quando tudo estiver configuradinho, você vai precisar fazer o seu primeiro commit, que nada mais é que jogar os seus tokens na branch do repositório.

 

 

Toda vez que fizer alguma alteração de tokens, lembre-se de:

 

👉 Gerar os estilos dos novos tokens no Figma através do botão Styles > Create Styles do Figma Tokens (a atualização dos estilos já é feita de forma automática, mas você tem que publicar a lib);

 

👉 Dar o “push” no Github, que irá atualizar o arquivo de tokens lá.

 

 

 


Entrando em ação com o Style Dictionary

 

Lembra que eu falei sobre a complementação do artigo do @sergio ? Agora já é uma boa hora de você dar uma olhadinha lá para entender como configurar o Style Dicionary. Mas, ao contrário do que o Sérgio fez, a gente vai clonar o nosso repositório do github e trabalhar lá!

 

Essa é a parte em que o bicho pega!

 

Se você criou seus sets no Figma Tokens e sincronizou com o GitHub, vai notar que o arquivo JSON gerado no GitHub traz a chave-pai e no Figma Tokens não. Isso acaba sendo uma verdadeira dor de cabeça. 😩

 

A divergência entre arquivos JSON do Figma Tokens e Github

A divergência entre arquivos JSON do Figma Tokens e Github

 

O problema aqui é que, quando você insere aliases tokens apontando para outro set, no Figma Token a chave fica {color.fuji.bright}, mas este mesmo valor não é traduzido pelo Style Dicionary pelo simples fato de não possuir a chave “global” ({global.color.fuji.bright}).

 

Essa incompatibilidade me tirou horas e horas de sono. Cheguei até a entrar em contato com o criador do plugin pra ver se existia alguma saída que não fosse mergulhar de cabeça em funções javascript que conseguissem reestruturar a nomenclatura dentro do Style Dictionary antes das conversões.

 

O próprio criador do plugin deu uma solução para este problema (e já falou que está trabalhando em uma alternativa melhor) que é o script token-transformer. Escrito por ele, esse script pega o JSON do Figma e gera um (ou mais) JSONs que o Style Dictionary consegue ler.

 

A primeira coisa que este script faz é remover a chave-pai, só que, a segunda coisa que ele faz é resolver os aliases… 😫 Ou seja, meus JSONs finais, ao invés de possuirem o apontamento aliases ({color.fuji.bright}), vai conter o valor (#FFFFFF).

 

Isso pode ou não ser um problema pra vocês:

 

👎 Vai ser um problema se o time de desenvolvimento tiver liberdade para alterar valores de tokens no código, por que sem os apontamentos aliases, eles não serão refletidos.

 

👍 Não vai ser um problema se toda atualização de tokens vier do Figma, por que dessa forma, os tokens passarão sempre pelo token-transformer, e pelo build do Style Dictionary, portanto, mesmo com os valores resolvidos, eles vão se manter atualizados.

 

Logo depois que esse script for executado, você pode então executar o build do Style Dictionary, apontando como fonte (source) a pasta dos JSONs que foram gerados. Voilá! Você agora tem todos os arquivos de tokens que precisa.

 


Scripts e dicas pra você não sofrer como eu sofri

 

Não vou entrar em detalhes sobre as configurações do Style Dictionary, por que o @sergio já fez isso muito bem em seu artigo “Design Tokens – Do Figma até o código”, mas existem algumas pegadinhas que me tiraram algumas horas:

 

 

Convertendo sombras que possuem um array de valores

 

Se você usa combinações de sombras nos seus projetos (ex.: box-shadow: 0px 2px 2px rgba(6, 13, 38, 0.15), 0px 4px 10px rgba(6, 13, 38, 0.15);), vai perceber que ao converter seus tokens, o Style Dictionary não vai conseguir devolver o valor. Para que isso se resolva, utilize o seguinte script em build.js:

 

// chama o modulo Tinycolor2
const Color = require("tinycolor2");

//transforma cores HEX em RGB
StyleDictionary.registerTransform({
  name: "color/css",
  type: "value",
  matcher: function (prop) {
    return prop.attributes.category === "color";
  },
  transformer: function (prop) {
    var color = Color(prop.value);
    if (color.getAlpha() === 1) {
      return color.toHexString();
    } else {
      return color.toRgbString();
    }
  },
});

//registra o formato da chave de sombra
StyleDictionary.registerTransform({
  name: "shadow/css",
  type: "value",
  matcher: function (token) {
    return token.type === "boxShadow";
  },
  transformer: (token) => {
    const shadows = Object.values(token.value);
    const result = shadows.map(
      (shadow) =>
        `${shadow.x} ${shadow.y} ${shadow.blur} ${shadow.spread} ${shadow.color}`
    );
    return result.join(",");
  },
});

 

Nas configurações de exportação insira as transformações "color/css", "shadow/css".

 

 

Criando workflows no Github

 

Você sabia que é possível rodar todo esse processo quando o designer der um push do Figma para o GitHub? Basta criar um arquivo YAML e alocá-lo na pasta .github/workflow no seu repositório. Pra facilitar a configuração desse arquivo, Michael Mang criou uma ferarmenta bem intuitiva.

 

 


 

Depois que tudo estiver rodando belezinha, vocês precisam determinar como vão distribuir o pacote de Design Tokens para que seja utilizado por times de desenvolvimento. A sugestão aqui é criar e publicar um pacote NPM para entregar mais flexibilidade aos time de desenvolvimento sobre atualizar ou não os tokens, visando os possíveis impactos.

 

É trabalhoso, mas uma vez que esse processo está rodando, é só alegria! 🎉🎉

 


 

Tudo que você precisa:

 

  1. Plugin Figma Tokens:
    https://www.figma.com/community/plugin/843461159747178978
  2. NodeJS:
    https://nodejs.org/en/
  3. GitHub:
    https://github.com/
  4. NPM:
    https://npmjs.com

 

 

E aí? Vamos botar a mão na massa?

Que tal dar uma lida em: