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 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
- 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
- Arquivo escondido na publicação
- 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
- Peças de montagem escondidas na publicação
- Descontinuados ficam até a próxima major
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ável | Tipo | Modo 1 | Modo 2 | Sintaxe de código (Web) |
|---|---|---|---|---|
| Primitivos · um modo, escondidos na publicação | ||||
color. | Cor | #1F5FAE | (um modo) | não publicada |
color. | Cor | #5B95DB | (um modo) | não publicada |
color.ink.900 | Cor | #14202B | (um modo) | não publicada |
color.sand.50 | Cor | #FBF8F2 | (um modo) | não publicada |
space.3 · space.4 | Número | 12 · 16 | (um modo) | não publicada |
| Cor · modos Light e Dark | ||||
color. | Cor | → blue.600 | → blue.400 | var(--hb-color-action-primary) |
color. | Cor | → ink.900 | → sand.50 | var(--hb-color-text-default) |
color. | Cor | → sand.50 | → ink.900 | var(--hb-color-surface-default) |
| Densidade · modos Comfortable e Compact | ||||
space. | Número | → space.4 (16) | → space.3 (12) | var(--hb-space-inset-md) |
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.mdvale 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.controlao 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 deTypeno 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.600em vez deaction.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)
- Escreva as páginas do principal arquivo Figma do seu time, de cima para baixo.
- Marque cada uma: uma pessoa nova saberia para que ela serve só pelo nome?
- 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
- Figma Help Center: Guide to libraries in Figma · Publish a library · Overview of variables, collections, and modes · Create and manage variables and collections · Modes for variables · Explore component properties · Figma plans and features (todos conferidos em novembro de 2026)
Livros, cursos e vídeos para ir mais fundo
- Design SystemsAlla KholmatovaLivro · Smashing Magazine, 2017 (Amazon)
- Atomic DesignBrad FrostBrad Frost, 2016 · grátis para ler online (Amazon)
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