Marcus Andrey Estudo
Read in English Biblioteca

Design systems · Passo 5 · 10 min de leitura

Montar uma biblioteca no Figma

Uma biblioteca do Figma é a metade de design do sistema: o arquivo de onde os outros arquivos puxam componentes, estilos e variáveis. Como dividir em arquivos e páginas, como os tokens do Harbour viram variáveis com modos, como dar aos componentes propriedades que batem com o código, e o que a publicação exige e em qual plano.

Uma ponte levadiça sobre um canal: dois cais, uma folha articulada em cada um e o mesmo bloco nas duas margens. Leve o ponteiro para o meio do canal e as duas folhas descem até se encontrarem niveladas; vá para cima dos cais e elas sobem de novo. Este passo é isso: a biblioteca do Figma e o código são duas margens com o mesmo componente, e o trabalho é manter entre elas uma passagem que os dois lados consigam atravessar. Este passo tem quatro lições: como montar uma biblioteca no Figma, Code Connect e a ponte entre design e código, Storybook e documentação viva, e versionamento e releases.Ilustração: Marcus Andrey, desenhada com Hairline (MIT, Lucas Marques).

Uma biblioteca é uma promessa para cada designer que a ativa: isto é o de verdade, e vai continuar aqui no mês que vem. Um arquivo cheio de bons componentes ainda não é uma biblioteca. Ele vira uma quando outros arquivos podem depender dele: com os nomes que o código usa, organizado para as pessoas acharem as coisas sem perguntar, e publicado com uma nota dizendo o que mudou. Esta aula é sobre construir bem essa metade da ponte, para a próxima aula ligar a outra ponta ao código.

O que você vai conseguir fazer depois de ler:

  • Explicar o que é uma biblioteca no Figma e o que pode ir nela
  • Dividir uma biblioteca em arquivos e páginas em que as pessoas se achem
  • Transformar um conjunto de tokens em variáveis, coleções e modos
  • Publicar uma biblioteca de propósito, no plano certo e com uma nota para cada mudança

1. O que é uma biblioteca, nas palavras do Figma

O Figma define sem rodeio: "a library is a collection of design assets, like components, styles, and variables", ou seja, uma coleção de componentes, estilos e variáveis que vivem num arquivo e "can be reused across different files", podem ser reutilizados em outros arquivos (Figma, Guide to libraries). Um arquivo pode ser publicado assim que tiver pelo menos um componente, estilo ou variável (Figma, Publish a library).

Plano: publicar bibliotecas está nos planos Professional, Education, Organization, Government e Enterprise. No plano gratuito Starter você cria componentes, mas não consegue publicá-los para outros arquivos usarem (Figma, Publish a library). Usar variáveis dentro de um arquivo funciona em todos os planos (Figma, Guide to variables).

Se você veio de O que é um design system, esta é a parte "biblioteca de componentes" das quatro, vista de dentro do Figma. É só metade: a outra metade é o código, e o sistema é o acordo entre as duas.


2. Arquivos e páginas em que as pessoas se achem

Harbour Foundations publicado como biblioteca
  • Capa nome, versão, responsável
  • Leia-me como ativar, onde está a documentação
  • Changelog uma entrada por publicação
  • Fundamentos
  • Cor variáveis, claro e escuro
  • Tipografia estilos de texto
  • Espaço, raio e densidade variáveis de número
  • Elevação estilos de efeito
  • Ícones um componente por ícone
  • Não usar
Harbour Components usa Foundations
  • Capa nome, versão, responsável
  • Leia-me como ativar, onde está a documentação
  • Changelog uma entrada por publicação
  • Componentes, de A a Z
  • Botão conjunto de variantes + notas de uso
  • Cartão de travessia
  • Campo de texto
  • Diálogo
  • Seleção
  • Não usar
A biblioteca Figma do Harbour em dois arquivos, vista pelo painel de páginas. Foundations guarda as variáveis e os estilos; Components usa esses valores e guarda os componentes, um por página, em ordem alfabética. Todo arquivo abre com as mesmas três páginas, então todo mundo sabe onde estão a versão, as instruções e as mudanças. Os nomes das páginas e a divisão são escolha do Harbour, não regra do Figma.

O Figma não diz como organizar uma biblioteca, então você decide e escreve a decisão. O que o Harbour faz, e por quê:

  • Dois arquivos, não um. Foundations (variáveis, estilos de texto, efeitos, ícones) muda pouco; os componentes mudam toda semana. Separar significa que uma mudança de cor não vai na mesma publicação que um diálogo novo, e times que só precisam dos fundamentos, como o marketing, ativam só aquele arquivo. Não divida mais até um arquivo ficar lento ou ter dois responsáveis.
  • As mesmas três primeiras páginas em todo arquivo: uma capa com nome, versão e responsável, um leia-me com como ativar a biblioteca e onde está a documentação, e um changelog. Ninguém deveria precisar perguntar "que versão é essa?".
  • Uma página por componente, em ordem alfabética, com o conjunto de variantes no topo e as notas de uso ao lado.
  • Um lugar claro para o que não é para usar. As peças de montagem (as partes de que um componente é feito) e os componentes descontinuados ficam no arquivo, mas escondidos na publicação, para não aparecerem no painel de assets das pessoas. O Figma deixa você clicar com o botão direito em qualquer asset no modal da biblioteca e escolher Hide when publishing (Figma, Publish a library).

3. Tokens viram variáveis

VariávelTipoModo 1Modo 2Sintaxe de código (Web)
Primitivos · um modo, escondidos na publicação
color.blue.600Cor#1F5FAE(um modo)não publicada
color.blue.400Cor#5B95DB(um modo)não publicada
color.ink.900Cor#14202B(um modo)não publicada
color.sand.50Cor#FBF8F2(um modo)não publicada
space.3 · space.4Número12 · 16(um modo)não publicada
Cor · modos Light e Dark
color.action.primaryCor→ blue.600→ blue.400var(--hb-color-action-primary)
color.text.defaultCor→ ink.900→ sand.50var(--hb-color-text-default)
color.surface.defaultCor→ sand.50→ ink.900var(--hb-color-surface-default)
Densidade · modos Comfortable e Compact
space.inset.mdNúmero→ space.4 (16)→ space.3 (12)var(--hb-space-inset-md)
Os tokens do Harbour como variáveis do Figma, em três coleções. Os primitivos guardam os valores brutos e ficam fora da biblioteca publicada, para quem desenha escolher significados, não códigos hex. As variáveis semânticas são aliases: em cada modo apontam para um primitivo diferente. O campo de sintaxe de código é o que o Dev Mode mostra para quem desenvolve, então leva o mesmo nome da custom property do CSS.

No Figma, os tokens vivem como variáveis. O Figma lista seis tipos (cor, número, string, booleano e os mais novos timing e easing) e agrupa as variáveis em coleções: "a set of variables and modes", um conjunto de variáveis e modos. Um modo é "a list of values for a variable in a collection, storing one value per variable", uma lista que guarda um valor por variável, e é assim que a mesma variável pode ser blue.600 no claro e blue.400 no escuro (Figma, Overview of variables, collections, and modes). A teoria está em Níveis de tokens e Temas e modos; aqui está como o Harbour organiza:

  • Primitivos: uma coleção, um modo, valores brutos (color.blue.600 = #1F5FAE, space.4 = 16). Escondidos na publicação, para quem desenha escolher significados, não códigos hex.
  • Cor semântica: uma coleção com os modos Light e Dark. Toda variável é um alias: o Figma deixa uma variável "reference other variables of the same type", apontar para outras variáveis do mesmo tipo (Figma, Create and manage variables).
  • Densidade: uma coleção com os modos Comfortable e Compact, para o console da equipe: space.inset.md vale 16 num e 12 no outro.

Três configurações importam mais do que parecem:

  • Escopo (scoping) limita a quais propriedades a variável pode ser aplicada, para variáveis de número, cor e string. Limite radius.control ao raio de canto, e ninguém usa por engano como espaçamento.
  • Sintaxe de código: cada variável pode ter "one name per platform, including Web, Android, and iOS", um nome por plataforma, e o Dev Mode mostra esse nome nos trechos de código em CSS, SwiftUI e Compose (Figma, Create and manage variables). Coloque var(--hb-color-action-primary) e quem desenvolve vê o nome real, não um palpite.
  • Modos nos frames: os objetos começam em Auto e "take on the mode of their parent container", herdam o modo do contêiner pai (Figma, Modes for variables). Coloque Dark no frame, e tudo dentro acompanha.

Plano: o número de modos por coleção depende do plano. A página de planos do Figma lista até 10 no Professional, até 20 no Organization e modos ilimitados com coleções estendidas no Enterprise (Figma, Plans and features). Dois modos para claro e escuro, e dois para densidade, cabem em qualquer plano pago. O caminho dessas variáveis até o código está em Tokens do Figma ao código.


4. Componentes com propriedades que batem com o código

As propriedades de um componente no Figma são a API dele no design, e deveriam se parecer com a API do código (veja Anatomia e API de um componente). O Figma tem cinco tipos: variante, booleana (que por enquanto "only support layer visibility", só liga e desliga a visibilidade de camadas), instance swap, texto e slot, "a flexible area in a component where you can add, edit, and rearrange content", uma área flexível onde você adiciona, edita e reorganiza conteúdo (Figma, Explore component properties). Variantes, propriedades e slots mostra quando usar cada uma. Na biblioteca, três hábitos mantêm tudo honesto:

  • Os mesmos nomes do código, sempre que der. Se o código diz variant, não chame de Type no Figma. Onde os nomes diferem, o mapeamento da próxima aula precisa traduzir, e cada tradução é um lugar para as duas versões se afastarem.
  • Menos variantes, mais propriedades. Uma booleana para "mostrar ícone" é melhor do que dobrar o conjunto de variantes.
  • Instâncias preferidas nos instance swaps, para o slot de ícone oferecer primeiro os ícones do Harbour, não a biblioteca inteira.

5. Publicar de propósito

Toda publicação pede uma descrição, e o Figma mostra essa descrição quando as pessoas aceitam a atualização e no histórico de versões do arquivo. Quem usa a biblioteca vê um selo e pode "review and accept the updates", revisar e aceitar as atualizações no seu tempo (Figma, Publish a library). Esse último ponto importa: uma publicação não muda o arquivo de ninguém até a pessoa aceitar. Então:

  • Escreva a descrição como uma linha de changelog: o que mudou e se alguém precisa fazer alguma coisa.
  • Publique em lotes que correspondem a uma versão, não a cada pixel ajustado (Versões e releases).
  • Admins podem definir bibliotecas padrão para um time ou organização, para todo arquivo novo já começar com o Harbour ativado (Figma, Guide to libraries). Essa configuração faz mais pela adoção do que um e-mail de lançamento.

6. Erros comuns

  • Um arquivo gigante com tudo, que fica lento e não tem ninguém responsável por nenhuma parte.
  • Publicar os primitivos, e as pessoas escolhem blue.600 em vez de action.primary, e o modo escuro quebra.
  • Nomes no Figma que não batem com os do código, sem ninguém cuidando da tradução.
  • Publicar com a descrição vazia.
  • Deixar componentes descontinuados visíveis, e o trabalho novo continua usando.
  • Criar variantes para cada combinação em vez de usar propriedades booleanas, de texto e slots.

7. Vocabulário

Termo Significado
Biblioteca Um arquivo do Figma cujos componentes, estilos e variáveis outros arquivos podem usar
Variável Um valor com nome, reutilizável no Figma: cor, número, string, booleano, timing ou easing
Coleção Um conjunto de variáveis e dos modos que elas compartilham
Modo Um conjunto de valores para uma coleção, como Light ou Compact
Alias Uma variável cujo valor é outra variável
Escopo Limitar a quais propriedades uma variável pode ser aplicada
Sintaxe de código O nome que a variável tem no código, mostrado no Dev Mode
Hide when publishing Manter um asset no arquivo da biblioteca, mas fora do painel de assets das outras pessoas

8. Experimente (sem ferramentas)

  1. Escreva as páginas do principal arquivo Figma do seu time, de cima para baixo.
  2. Marque cada uma: uma pessoa nova saberia para que ela serve só pelo nome?
  3. Escreva as três páginas com que todo arquivo deveria abrir, e uma página que você esconderia.

Perguntas para refletir: Se alguém do desenvolvimento olhasse suas variáveis no Dev Mode hoje, os nomes bateriam com alguma coisa no código? Quem decide quando a biblioteca é publicada?


9. Se você já pratica

  • Revise os assets publicados no modal da biblioteca: o que as pessoas não devem escolher fica escondido.
  • Preencha a sintaxe de código de toda variável semântica e confira com as custom properties do CSS.
  • Ative o escopo nas variáveis de espaçamento e raio, e veja quantos usos errados somem.
  • Combine com a engenharia um único ritmo de releases para a biblioteca e o pacote.

Checklist

Para saber mais

Livros, cursos e vídeos para ir mais fundo

Os links dos livros são de afiliado da Amazon: como associado, recebo por compras qualificadas, sem custo a mais para você.

Relacionadas

Tokens do Figma ao código · Temas e modos · Variantes, propriedades e slots · Desenhe um componente com variantes no Figma · Handoff para desenvolvedores

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar