Arquitetura de bibliotecas e padrões de organização de páginas e camadas

Uma biblioteca bem arquitetada no Figma reduz retrabalho, evita divergências entre times e torna o handoff mais previsível. “Arquitetura de bibliotecas” aqui significa definir como os arquivos, páginas, frames e camadas serão organizados para que qualquer pessoa encontre, use e mantenha componentes e estilos com o mínimo de ambiguidade. O objetivo não é “deixar bonito”, e sim criar um sistema de navegação e manutenção: onde cada coisa mora, como é nomeada, como é versionada e como é auditada.

O que é arquitetura de bibliotecas no Figma

No Figma, biblioteca é o conjunto de recursos publicáveis (componentes, estilos, variáveis/tokens, etc.) que outros arquivos podem consumir. A arquitetura da biblioteca é a combinação de:

• Estrutura de páginas: como você separa fundações, componentes, padrões, templates e documentação.
• Estrutura interna de cada página: seções, frames, grids de componentes, áreas de playground e áreas de documentação.
• Padrões de camadas: como você nomeia, agrupa e ordena layers dentro de componentes para facilitar manutenção e inspeção.
• Regras de publicação: o que é publicável, o que é interno, como lidar com depreciação e compatibilidade.

Uma boa arquitetura precisa equilibrar dois públicos: quem consome (quer achar e usar rápido) e quem mantém (quer editar sem quebrar dependências). O erro comum é organizar só para manutenção (muito técnico) ou só para consumo (muito “catálogo”), e a biblioteca vira difícil de evoluir.

Princípios práticos para guiar a organização

1) Encontrabilidade acima de preferência pessoal

Se duas pessoas diferentes não conseguem prever onde um componente está, a arquitetura falhou. Prefira estruturas previsíveis e repetíveis, mesmo que não sejam as “mais criativas”.

2) Separar “fonte de verdade” de “exemplos”

Componentes devem ter uma área clara onde são editados (fonte) e outra onde são demonstrados (exemplos). Misturar os dois aumenta o risco de alguém editar o exemplo achando que é o master.

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

3) Minimizar acoplamento entre páginas

Quanto mais um componente depende de elementos soltos em outras páginas (ícones não publicados, estilos locais, frames de referência), maior a chance de quebrar ao mover/duplicar. Prefira dependências publicadas e centralizadas.

4) Consistência de padrões de camada

Mesmo que o componente seja complexo, a pessoa que vai dar manutenção precisa reconhecer padrões: onde está o container, onde estão slots, onde ficam ícones, labels, estados e overlays.

Padrões de organização de páginas (modelos recomendados)

A seguir estão modelos de páginas que funcionam bem para bibliotecas de Design System. Você pode adaptar nomes, mas mantenha a lógica.

Modelo A: Biblioteca por níveis (Fundações → Componentes → Padrões)

• 00 — Start / Read me: instruções rápidas, links internos, regras de uso, status da biblioteca, changelog resumido.
• 01 — Foundations: cores, tipografia, espaçamentos, grids, elevação, ícones (se forem parte do DS), motion specs (se documentado visualmente).
• 02 — Components: componentes atômicos e compostos (Button, Input, Select, Card, Modal etc.).
• 03 — Patterns: combinações recorrentes (Form layout, Empty states, Filters bar, Pagination patterns).
• 04 — Templates: telas base (Dashboard shell, Auth layout, Settings layout) quando fizer sentido para o produto.
• 90 — Playground: área para testes e experimentos controlados (não publicar nada daqui).
• 99 — Archive / Deprecated: itens antigos, mantidos por compatibilidade, com marcação clara.

Esse modelo é forte quando você quer separar o que é “peça” do que é “composição”. Ajuda a evitar que templates virem a fonte de verdade de componentes.

Modelo B: Biblioteca por domínio (Web, Mobile, Marketing)

• 00 — Start / Read me
• 01 — Shared Foundations: o que é comum a todos os domínios.
• 02 — Web: componentes e padrões específicos de web.
• 03 — Mobile: componentes e padrões específicos de mobile.
• 04 — Marketing: componentes e blocos de landing pages, banners, etc.
• 99 — Archive / Deprecated

Esse modelo funciona quando há variações reais de plataforma (ex.: web tem tabelas complexas; mobile tem bottom sheets; marketing tem blocos editoriais). O cuidado é não duplicar o mesmo componente em várias páginas; prefira “Shared” sempre que possível.

Modelo C: Biblioteca por categoria de componente

• Inputs: Text field, Select, Checkbox, Radio, Switch, Date picker.
• Navigation: Tabs, Sidebar, Breadcrumb, Pagination.
• Feedback: Toast, Alert, Tooltip, Modal.
• Data display: Table, List, Card, Badge, Tag.

É intuitivo para consumo, mas pode dificultar manutenção de fundações e padrões. Se usar esse modelo, mantenha uma página separada para Foundations e outra para Patterns.

Estrutura interna de páginas: seções e frames

Independentemente do modelo de páginas, padronize a estrutura dentro de cada página. Um padrão simples e eficaz é dividir a página em blocos horizontais (ou seções) com frames bem nomeados.

Layout sugerido dentro da página de um componente

• Header do componente: nome, status (Stable/Beta/Deprecated), responsáveis, links para specs.
• Masters (fonte): todos os componentes principais (component sets) e subcomponentes necessários.
• Anatomia: um frame explicando partes (container, label, icon, helper text etc.).
• States & Variants: exemplos de combinações importantes (default, hover, pressed, disabled, loading, error).
• Do / Don’t: exemplos visuais de uso correto e incorreto (quando aplicável).
• Playground local: área para testar combinações sem mexer nos masters (com instâncias, não masters).

O ponto crítico é: Masters sempre em uma área isolada, com fundo neutro e sem elementos decorativos. Isso reduz o risco de alguém arrastar um master para fora, ou confundir instância com master.

Como organizar “Masters” em grids previsíveis

Para componentes com muitas variantes, organize os component sets em uma grade com espaçamento consistente e alinhamento. Exemplo: uma coluna por tamanho (S/M/L) e uma linha por tipo (Primary/Secondary/Tertiary). Mesmo que o Figma tenha painel de variantes, a organização visual ajuda manutenção.

Exemplo de grid visual (não é código executável):  Colunas: Size = S | M | L  Linhas: Variant = Primary | Secondary | Ghost  Dentro de cada célula: instância representativa do estado Default

Padrões de organização de camadas (layers) dentro de componentes

O padrão de camadas é o que mais impacta manutenção. Quando alguém abre um componente para ajustar padding, trocar um ícone ou corrigir um estado, a clareza das layers economiza tempo e evita bugs visuais.

Regra 1: Nomear por função, não por aparência

Evite nomes como “Rectangle 12” ou “Blue bg”. Prefira nomes que descrevem o papel do elemento:

• Container (ou Surface): fundo e borda do componente.
• Content: grupo/auto layout com conteúdo principal.
• Label: texto principal.
• Icon/Leading e Icon/Trailing: ícones antes/depois do texto.
• Helper, Error, Counter: textos auxiliares.
• Overlay: camada para estados (hover/pressed) quando aplicável.
• Focus ring: anel de foco separado, fácil de ligar/desligar.

Regra 2: Ordem de camadas previsível

Uma ordem comum (de baixo para cima) facilita inspeção:

• Container / Surface
• Overlay (hover/pressed)
• Content (texto/ícones)
• Focus ring
• Badges/Indicators (se existirem)

Se cada componente segue uma ordem diferente, a manutenção vira tentativa e erro.

Regra 3: Evitar profundidade desnecessária

Camadas demais (grupos dentro de grupos) dificultam seleção e aumentam chance de constraints errados. Use Auto Layout para reduzir wrappers. Crie wrappers apenas quando tiver um motivo claro: alinhar, aplicar padding específico, controlar overflow, ou separar slots.

Regra 4: Slots explícitos para composição

Quando um componente é “container” (Card, List item, Modal), defina slots claros:

• Header
• Body
• Footer

Mesmo que o slot esteja vazio em algumas variantes, a previsibilidade ajuda quem vai inserir conteúdo. Em Auto Layout, isso também facilita manter espaçamentos consistentes.

Regra 5: Elementos opcionais com visibilidade controlada

Para partes opcionais (ícone, helper text, prefix/suffix), prefira controlar via variantes ou propriedades (quando fizer sentido) e mantenha o nome da layer constante. Exemplo: sempre “Icon/Leading”, mesmo quando oculto. Isso evita que instâncias quebrem ao trocar variante.

Nomenclatura: páginas, frames, componentes e variantes

Uma arquitetura consistente depende de nomenclatura. O objetivo é permitir busca rápida (Ctrl/Cmd + F) e leitura sem contexto.

Páginas

Use prefixos numéricos para manter ordem estável e facilitar onboarding:

00 — Start 01 — Foundations 02 — Components 03 — Patterns 90 — Playground 99 — Archive

Frames de documentação

Padronize títulos curtos e repetíveis:

• Anatomy
• Variants
• States
• Usage
• Do / Don’t
• Accessibility notes (se você documentar visualmente)

Componentes

Nomeie componentes com substantivos claros e consistentes. Evite sinônimos para a mesma coisa (Button vs CTA). Se o produto usa um termo específico, adote-o e documente.

Para componentes com hierarquia, use separadores:

Button  Button / Icon  Button group  Text field  Text field / Helper row

O separador “/” cria agrupamento natural no painel de Assets.

Variantes

Defina um conjunto fixo de propriedades de variante por componente. Exemplo para Button:

• Variant: Primary, Secondary, Ghost
• Size: S, M, L
• State: Default, Hover, Pressed, Disabled, Loading
• Icon: None, Leading, Trailing, Only

Evite criar propriedades redundantes (ex.: “Disabled = true” e também “State = Disabled”). Escolha uma abordagem e mantenha.

Passo a passo prático: desenhando a arquitetura de uma biblioteca do zero

Passo 1: Liste o inventário e agrupe por nível

Antes de criar páginas, faça um inventário simples do que a biblioteca precisa conter. Agrupe em:

• Fundações (cores, tipografia, espaçamento, radius, elevação)
• Componentes (UI reutilizável)
• Padrões (combinações recorrentes)
• Templates (se aplicável)

Esse inventário evita criar páginas “por impulso” e ajuda a escolher o modelo A/B/C.

Passo 2: Escolha um modelo de páginas e fixe a ordem

Escolha um dos modelos e crie as páginas com prefixo numérico. Não tente antecipar todas as páginas futuras; crie as macroáreas e deixe espaço para crescer.

Passo 3: Defina um “template” de página de componente

Crie uma página exemplo (por exemplo, para Button) e defina a estrutura interna (Masters, Anatomy, States, Usage, Playground). Depois replique o padrão para os demais componentes. A repetição é o que torna a biblioteca navegável.

Passo 4: Padronize camadas com um checklist

Crie um checklist de layers para cada tipo de componente. Exemplo para um input:

• Container
• Label
• Field (área do texto)
• Placeholder
• Value
• Icon/Leading (opcional)
• Icon/Trailing (opcional)
• Helper text / Error text
• Focus ring

Ao construir novos componentes, siga o checklist para manter consistência.

Passo 5: Separe “Masters” de “Instâncias de exemplo”

No frame “Masters”, mantenha apenas component sets e subcomponentes necessários. No frame “Examples/Usage”, use instâncias. Uma regra prática: se você precisa editar uma layer e isso deve refletir em todo lugar, você está no master; se é apenas demonstração, é instância.

Passo 6: Crie uma área de “Deprecated” com regras claras

Quando um componente mudar de forma incompatível, você precisa de um lugar para manter versões antigas por um tempo. Na página 99 — Archive/Deprecated:

• Mantenha componentes antigos com prefixo “Deprecated / …”
• Inclua um frame com: motivo, substituto recomendado, data de depreciação
• Evite editar visualmente o antigo (apenas correções críticas)

Isso reduz o caos de arquivos paralelos e dá previsibilidade para migrações.

Passo a passo prático: organizando uma página de componentes (exemplo: Buttons)

Passo 1: Crie seções fixas

Dentro da página “02 — Components”, crie um frame grande “Button” e dentro dele crie subframes:

• Button — Masters
• Button — Anatomy
• Button — Variants
• Button — States
• Button — Usage
• Button — Playground

Passo 2: Construa o component set no frame Masters

Coloque o component set principal no topo esquerdo do frame Masters e mantenha subcomponentes abaixo (por exemplo, “Spinner” se for interno ao botão). Garanta que o component set tenha propriedades de variante coerentes (Variant/Size/State/Icon).

Passo 3: Documente anatomia com nomes iguais aos layers

No frame Anatomy, mostre uma instância do botão com setas/labels. Use os mesmos nomes das layers (“Container”, “Label”, “Icon/Leading”). Isso cria um vocabulário comum entre design e desenvolvimento e facilita revisão.

Passo 4: Crie exemplos de estados críticos

No frame States, não precisa mostrar todas as combinações possíveis (isso vira ruído). Mostre as combinações que mais geram dúvidas:

• Default vs Disabled
• Hover/Pressed (se aplicável ao contexto)
• Loading com e sem label
• Icon only (tamanhos e área de clique)

Passo 5: Reserve um playground com instâncias destravadas

No Playground, mantenha instâncias para testes rápidos (trocar texto, trocar ícone, simular layout). Isso evita que pessoas criem “forks” do componente fora da biblioteca por falta de um lugar para experimentar.

Padrões para páginas de Foundations e Patterns

Foundations: organize por “decisão” e não por “artefato”

Em vez de uma página “Cores” com dezenas de amostras soltas, organize por decisões de uso. Exemplos de frames úteis:

• Color roles: Background, Surface, Text, Border, Brand, Danger, Warning, Success.
• Contrast checks: exemplos de combinações aprovadas.
• Elevation: níveis e quando usar.
• Spacing scale: escala e exemplos de aplicação.

Isso ajuda quem consome a entender “qual usar” e não apenas “quais existem”.

Patterns: documente composição e regras

Padrões são onde a biblioteca costuma virar “galeria”. Para evitar isso, cada pattern deve ter:

• Objetivo (quando usar)
• Estrutura (quais componentes compõem)
• Regras (espaçamentos, ordem, comportamento)
• Variações (quando realmente mudam a lógica)

Exemplo de pattern: “Form section”. Mostre como agrupar campos, onde entram mensagens de erro, e como alinhar ações.

Governança leve: como evitar bagunça com o crescimento

Mesmo com boa arquitetura inicial, bibliotecas crescem. Algumas regras simples mantêm a organização:

Regra: toda nova página precisa de um motivo

Antes de criar uma nova página, pergunte: isso não cabe em uma página existente com seções? Páginas demais dificultam busca e aumentam duplicação.

Regra: todo novo componente precisa de “dono” e “local”

Defina quem mantém e em qual página entra. Componentes “órfãos” acabam duplicados porque ninguém sabe se já existe.

Regra: mudanças grandes exigem trilha de migração

Se um componente muda de API (variantes/propriedades), mantenha o antigo como Deprecated por um período e documente o substituto. Isso reduz quebras em arquivos consumidores.

Checklist rápido de auditoria de organização (para revisar uma biblioteca existente)

• As páginas têm ordem previsível e nomes consistentes?
• Existe uma página “Start/Read me” com regras e links?
• Masters estão separados de exemplos em todas as páginas?
• Componentes semelhantes seguem o mesmo padrão de layers (Container/Content/Overlay/Focus)?
• Os nomes de layers descrevem função (Label, Icon/Leading) e não aparência?
• Existe área de Playground para testes sem mexer nos masters?
• Existe área de Deprecated com substitutos documentados?
• Patterns têm regras de composição, não só screenshots?