Configurar bem o ambiente e a estrutura de arquivos no Figma é o que separa um Design System que escala (com governança, previsibilidade e handoff consistente) de uma biblioteca que vira “pasta de componentes” difícil de manter. Neste capítulo, o foco é montar uma arquitetura de arquivos e bibliotecas que suporte: múltiplos produtos, múltiplas marcas (se existir), evolução por versões, colaboração entre times e integração com desenvolvimento sem ruído.
O que significa “ambiente” no Figma para um Design System
Quando falamos em ambiente, não é só “ter um arquivo de componentes”. Ambiente inclui: como o time acessa e publica bibliotecas, como os arquivos se relacionam (tokens → componentes → templates), como as permissões são definidas, como se controla versão, como se documenta decisões e como se evita que cada squad crie variações paralelas.
Uma configuração de ambiente bem feita responde a perguntas práticas:
- Onde ficam os tokens (cores, tipografia, espaçamentos) e como eles são consumidos pelos componentes?
- Como um designer sabe qual biblioteca usar (e qual não usar)?
- Como mudanças são propostas, revisadas e publicadas?
- Como o desenvolvedor encontra a fonte da verdade e entende o status (draft, beta, estável)?
- Como lidar com múltiplas marcas/temas sem duplicar tudo?
Princípios para estruturar arquivos sem retrabalho
1) Separar “fonte da verdade” de “uso em produto”
Arquivos do Design System devem ser tratados como fonte da verdade (bibliotecas publicáveis). Arquivos de produto devem consumir essas bibliotecas, mas não devem virar o lugar onde componentes “nascem”. Isso reduz divergência e evita que correções fiquem presas em um projeto específico.
2) Modularizar por camadas (tokens → componentes → padrões)
Uma estrutura em camadas facilita manutenção e governança. Em vez de um arquivo gigante com tudo, você organiza por responsabilidade:
Continue em nosso aplicativo
Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.
ou continue lendo abaixo...
Baixar o aplicativo
- Tokens: estilos e variáveis (cores, tipografia, efeitos, espaçamentos, raios, etc.).
- Componentes: UI building blocks (botões, inputs, cards).
- Padrões: composições e templates (headers, formulários, empty states, fluxos).
Essa separação também ajuda a publicar bibliotecas com granularidade: às vezes você quer liberar tokens antes de liberar componentes, ou manter padrões como “opcionais”.
3) Evitar duplicação por marca/tema
Quando existe mais de uma marca (ou tema claro/escuro), o erro comum é duplicar componentes por tema. Em geral, é melhor manter componentes únicos e variar tokens/variáveis por tema. Isso mantém a lógica do componente consistente e reduz custo de manutenção.
4) Nomear e versionar para reduzir ambiguidade
Se o nome do arquivo e da biblioteca não deixa claro o que é “oficial”, as pessoas vão usar o que encontrarem primeiro. Nomes e descrições devem comunicar: escopo, status e compatibilidade.
Estrutura recomendada de arquivos (modelo prático)
A seguir, um modelo que funciona bem para times pequenos e grandes. Adapte o nível de granularidade conforme o tamanho do sistema.
Camada 1: Tokens e estilos (biblioteca base)
- DS — 00 Foundations (Tokens)
Conteúdo típico:
- Color styles (se ainda usar estilos) e/ou variáveis de cor
- Text styles e variáveis tipográficas
- Effect styles (sombras, blur)
- Grid/layout guidance (se aplicável)
- Spacing/radius como variáveis (quando fizer sentido)
Objetivo: ser a biblioteca mais estável e a primeira dependência dos componentes.
Camada 2: Componentes (biblioteca principal)
- DS — 01 Components (Core)
- DS — 02 Components (Extended) (opcional)
Separar Core e Extended é útil quando há um conjunto pequeno que todo produto usa (Core) e outro conjunto mais específico (Extended). Se o sistema ainda é pequeno, mantenha tudo em um arquivo.
Camada 3: Padrões e templates (biblioteca de composição)
- DS — 03 Patterns
- DS — 04 Templates (opcional)
Padrões são combinações recorrentes (ex.: “Filtro + Lista + Paginação”). Templates são telas ou estruturas mais completas (ex.: “Página de detalhes”). Em muitos times, templates não são publicados como biblioteca, mas mantidos como referência; isso depende do nível de padronização desejado.
Camada 4: Playground e QA
- DS — 90 Playground
- DS — 99 QA & Regression
Playground é onde você testa variações, experimenta e valida antes de promover para a biblioteca oficial. QA & Regression é um arquivo com páginas de “snapshot” para verificar se mudanças quebraram algo (principalmente útil quando há muitas variantes e estados).
Estrutura interna de páginas dentro de cada arquivo
Além de separar arquivos, padronize páginas internas. Isso reduz tempo de onboarding e evita que cada pessoa organize de um jeito.
Exemplo de páginas para “DS — 01 Components (Core)”
- 00 — Cover / How to use: regras rápidas, links para tokens, status da biblioteca.
- 01 — Changelog: registro de mudanças com data, autor, impacto.
- 10 — Components: componentes prontos e publicados.
- 20 — WIP: componentes em desenvolvimento (não publicados).
- 30 — Deprecations: componentes antigos com orientação de migração.
- 90 — Docs: exemplos, do/don’t, guidelines visuais.
Dentro de “Components”, organize por categorias (Inputs, Navigation, Feedback, Data display). Evite páginas demais; prefira seções e headings dentro da página quando possível.
Exemplo de páginas para “DS — 00 Foundations (Tokens)”
- 00 — Cover / Principles
- 10 — Color
- 20 — Typography
- 30 — Elevation & Effects
- 40 — Spacing & Radius
- 90 — Mapping (tabelas de mapeamento: token → uso)
A página “Mapping” é especialmente útil para reduzir dúvidas: por exemplo, mostrar quais tokens de cor são para texto, quais são para fundo, quais são para borda, e exemplos de uso.
Configuração de permissões e papéis (para evitar “biblioteca editada por acidente”)
Um Design System precisa de controle de edição. Se qualquer pessoa edita a biblioteca, o risco não é só “bagunça”: é quebra de consistência e perda de rastreabilidade.
Modelo simples de papéis
- Maintainers (Design System): editam e publicam bibliotecas.
- Contributors: podem propor mudanças via branches/arquivos de contribuição.
- Consumers (squads): usam bibliotecas publicadas, sem editar a fonte.
Na prática, configure o arquivo do DS para que apenas maintainers tenham permissão de edição. Contributors trabalham em cópias/branches e submetem para revisão.
Passo a passo: criando a estrutura do zero no Figma
Passo 1 — Criar um “hub” do Design System
Crie um projeto (Project) dedicado ao Design System, separado dos projetos de produto. Nomeie de forma inequívoca, por exemplo: “Design System — [Nome da empresa]”. Dentro dele, crie os arquivos conforme as camadas (Foundations, Components, Patterns, Playground, QA).
Checklist:
- Projeto exclusivo do DS
- Arquivos com prefixo “DS —”
- Descrição do arquivo preenchida (escopo, status, link para documentação)
Passo 2 — Definir convenções de nomenclatura antes de desenhar
Antes de criar componentes, defina convenções mínimas:
- Prefixos de arquivo: “DS — 00…”, “DS — 01…”
- Nome de páginas com numeração (ordem previsível)
- Nome de componentes com hierarquia (ex.: Button / Primary, Input / Text)
- Nome de propriedades/variantes (ex.: size=sm|md|lg, state=default|hover|disabled)
Essas convenções evitam retrabalho quando a biblioteca cresce e você precisa reorganizar.
Passo 3 — Montar Foundations (tokens) primeiro
No arquivo “DS — 00 Foundations (Tokens)”, crie e organize os tokens/estilos que serão consumidos pelos componentes. Mesmo que você ainda não tenha todos os tokens, comece com um conjunto mínimo viável:
- Cores: texto, fundo, borda, feedback (success/warning/error/info)
- Tipografia: estilos para headings, body, caption
- Raios e sombras mais usados
Estruture por intenção (semântica) e não por valor. Por exemplo, em vez de “Blue 500”, prefira “Text/Link” ou “Bg/Primary” (o nome exato depende do seu padrão). Isso facilita troca de tema e evolução.
Passo 4 — Criar Components consumindo Foundations
No arquivo “DS — 01 Components (Core)”, comece pelos componentes mais usados (botão, input, checkbox, select, modal). A regra é: componentes devem referenciar tokens/variáveis sempre que possível, em vez de valores soltos.
Organize cada componente com:
- Uma área de “Anatomy” (partes nomeadas)
- Uma área de “Variants” (todas as combinações suportadas)
- Uma área de “Usage” (exemplos rápidos)
Passo 5 — Publicar bibliotecas em ordem de dependência
Publique primeiro Foundations, depois Components, depois Patterns/Templates. Isso reduz erros de referência e facilita que consumidores atualizem bibliotecas com menos conflitos.
Rotina sugerida:
- Publicar “DS — 00 Foundations (Tokens)”
- Atualizar referências no arquivo de componentes (se necessário)
- Publicar “DS — 01 Components (Core)”
- Publicar Patterns/Templates quando estiverem estáveis
Passo 6 — Criar um arquivo Playground para contribuições
No “DS — 90 Playground”, crie páginas para experimentos e propostas. Exemplo:
- 10 — Proposals
- 20 — Experiments
- 30 — Review ready
O Playground é onde contributors podem trabalhar sem risco de afetar a biblioteca oficial. Quando algo é aprovado, você promove para o arquivo oficial (copiando/colando com cuidado para manter referências) e só então publica.
Passo 7 — Criar um arquivo de QA/Regression
No “DS — 99 QA & Regression”, crie páginas com “matrizes” de componentes (ex.: todos os estados de Button, todos os estados de Input). Isso permite comparar rapidamente antes/depois de uma mudança.
Exemplo de organização:
- 10 — Buttons matrix
- 20 — Forms matrix
- 30 — Navigation matrix
Quando você alterar tokens ou componentes, visite essas matrizes para identificar quebras visuais (contraste, padding, alinhamento, estados).
Estratégias para múltiplos temas e marcas (sem duplicar bibliotecas)
Quando há mais de um tema (ex.: light/dark) ou mais de uma marca, a estrutura de arquivos precisa suportar variação com o menor número de bibliotecas possível.
Modelo A: Um arquivo de componentes + tokens por tema
- DS — 00 Foundations (Tokens)
- DS — 00A Foundations (Theme Light)
- DS — 00B Foundations (Theme Dark)
- DS — 01 Components (Core)
Nesse modelo, os componentes referenciam tokens semânticos, e você alterna o conjunto de tokens conforme o tema. É útil quando o tema muda valores, mas a estrutura do componente é a mesma.
Modelo B: Um arquivo de tokens com variáveis por modo
Quando você consegue manter tokens em um único arquivo com modos (modes), fica mais simples para consumidores. Você define modos como “Light” e “Dark” e alterna no contexto do arquivo/projeto conforme a necessidade.
Cuidados:
- Garanta que nomes semânticos sejam consistentes entre modos
- Evite criar tokens “quebrados” que só existem em um modo
Modelo C: Componentes específicos por marca (apenas quando necessário)
Se marcas têm diferenças estruturais (não só cor), você pode ter:
- DS — 01 Components (Core)
- DS — 01B Components (Brand B overrides)
Use isso com parcimônia. Sempre que a diferença for apenas visual, prefira resolver via tokens/variáveis.
Como organizar documentação dentro do arquivo (sem virar um wiki)
Documentação no Figma deve ser objetiva e acionável. Em vez de longos textos, prefira:
- Regras curtas (do/don’t)
- Exemplos lado a lado
- Tabelas de propriedades (o que cada variante significa)
- Notas de acessibilidade quando impactam design (contraste, foco, estados)
Uma estrutura prática por componente:
- O que é: 1–2 frases
- Quando usar: lista curta
- Quando não usar: lista curta
- Conteúdo: regras de texto/ícones
- Estados: default/hover/pressed/disabled/focus
- Responsivo: comportamento em largura/altura
Changelog e depreciação: preparando o sistema para evoluir
Sem um changelog mínimo, consumidores descobrem mudanças “na marra”. E sem depreciação, você acumula componentes antigos que continuam sendo usados.
Changelog dentro do arquivo
Crie uma página “Changelog” com entradas padronizadas:
- Data
- O que mudou
- Tipo: fix | improvement | breaking change
- Impacto esperado
- Ação requerida (se houver)
2026-01-05 — Button: ajuste de padding (improvement) Impacto: layouts podem mudar 4px em altura Ação: revisar telas com botões size=smDeprecation com orientação de migração
Quando um componente será substituído, mova-o para “Deprecations” e deixe claro:
- Qual é o substituto
- Até quando será suportado
- Quais diferenças existem
Input / Legacy (deprecated) Substituto: Input / Text Motivo: padronização de estados e suporte a helper text Migração: trocar instância e mapear propriedades size/stateChecklist de qualidade para a estrutura (auditoria rápida)
Use esta lista para validar se sua configuração está pronta para escalar:
- Arquivos do DS estão separados de arquivos de produto
- Foundations/tokens existem e são dependência dos componentes
- Componentes estão em arquivo(s) publicáveis, com páginas WIP separadas
- Há um Playground para propostas e experimentos
- Existe um arquivo de QA/Regression com matrizes de estados
- Permissões impedem edição acidental da biblioteca oficial
- Nomenclatura de arquivos, páginas e componentes é consistente
- Changelog e Deprecations existem e são fáceis de encontrar
Passo a passo: migrando de um “arquivo único bagunçado” para uma estrutura em camadas
Se você já tem um arquivo grande com tudo misturado, a migração deve ser incremental para não quebrar o consumo.
Passo 1 — Congelar o arquivo atual como “Legacy”
Duplique o arquivo atual e renomeie o original para algo como “DS — Legacy (read-only)”. Ajuste permissões para evitar novas edições. Isso reduz a chance de o time continuar criando coisas no lugar antigo.
Passo 2 — Extrair Foundations primeiro
Crie “DS — 00 Foundations (Tokens)” e mova/reestruture estilos e variáveis. Se houver estilos duplicados, consolide por intenção. Evite mudar valores nesse momento; foque em organizar e nomear.
Passo 3 — Extrair componentes por prioridade
Crie “DS — 01 Components (Core)” e migre primeiro os componentes mais usados. Para cada componente migrado:
- Garanta que usa tokens/variáveis em vez de valores soltos
- Padronize nomes de variantes e propriedades
- Crie uma pequena seção de uso
Publique a biblioteca nova e peça para um squad piloto consumir. Ajuste o que for necessário antes de migrar o restante.
Passo 4 — Criar uma estratégia de convivência temporária
Durante a migração, é comum conviver com duas bibliotecas. Para reduzir confusão:
- Renomeie a biblioteca antiga com “Legacy” no nome
- Adicione aviso na capa do arquivo antigo: “Não usar para novos designs”
- Defina uma data a partir da qual novos arquivos de produto só podem usar a biblioteca nova
Passo 5 — Montar QA/Regression para evitar regressões
À medida que você migra componentes, crie matrizes no arquivo de QA. Isso ajuda a detectar inconsistências entre o legado e o novo (por exemplo, alturas diferentes, estados faltando, contrastes).
Modelo de nomenclatura de arquivos e bibliotecas (exemplos prontos)
Use nomes que comuniquem escopo e ordem:
- DS — 00 Foundations (Tokens)
- DS — 01 Components (Core)
- DS — 02 Components (Extended)
- DS — 03 Patterns
- DS — 90 Playground
- DS — 99 QA & Regression
Se houver múltiplas marcas:
- DS — 00 Foundations (Brand A)
- DS — 00 Foundations (Brand B)
- DS — 01 Components (Shared)
Se houver múltiplos produtos com necessidades específicas, evite criar “DS do Produto X” dentro do DS. Prefira extensões controladas (Extended) e padrões específicos em arquivos de produto, mas sempre consumindo o Core.
