← Voltar para artigos

18 de novembro de 2026

Antes do primeiro componente: aprendizados de um design system construído do zero

Capa do artigo sobre a construção de um design system do zero

Introdução

Construir um design system do zero parece, de fora, um trabalho de criar componentes bonitos. Na prática, a maior parte do esforço está em outro lugar: decidir o que entra, organizar para que as pessoas encontrem, documentar para que usem do jeito certo e entregar para o desenvolvimento sem ruído.

Nos últimos meses eu construí um design system praticamente do zero, numa empresa da área da saúde com vários produtos digitais rodando ao mesmo tempo. O ponto de partida foi um produto que já existia e times que já desenhavam telas sem um sistema. Hoje, a primeira versão reúne 49 componentes.

Este texto reúne o que aprendi nesse caminho, em quatro frentes: organização, documentação, handoff e o uso de IA (principalmente o Claude) para acelerar o trabalho. Se você está começando um DS sozinho ou com um time pequeno, a ideia é que você consiga otimizar (pelo menos um pouquinho) do seu trabalho com esse texto.

1. Antes do primeiro componente: inventário e escopo

A vontade natural é abrir o Figma e começar pelo botão. Resista. O primeiro entregável de um design system é um inventário do que já existe, porque é ele que mostra onde está a inconsistência que o DS vai resolver.

No meu caso, a base foi um produto real e em uso: o principal portal dos nossos usuários. Em vez de inventar componentes ideais, eu parti do que as pessoas já usavam e me perguntei, para cada elemento, três coisas:

  • Isso aparece em mais de uma tela ou produto?
  • Existem variações que deveriam ser uma coisa só?
  • O dev consegue implementar isso na plataforma que usamos? No nosso caso, o OutSystems, uma plataforma low-code que tem suas limitações. Todas foram contornadas, mas só porque a pergunta era feita antes do componente ficar pronto, e não depois.

O segundo aprendizado foi nomear o escopo da primeira versão. Chamar de V0 e separar as Foundations foi uma decisão importante: deixou claro para o time que aquilo não era o sistema completo, e sim a primeira camada estável. Isso tira o peso de ter que resolver tudo antes de lançar e dá permissão para evoluir.

💡 Dica prática: faça o inventário com prints lado a lado, agrupados por tipo de elemento. Ver doze botões diferentes na mesma tela convence stakeholders mais rápido que qualquer argumento.

2. Foundations primeiro, componentes depois

Componente sem foundation é só um desenho reutilizável. O que torna um componente parte de um sistema é ele consumir decisões que já foram tomadas em outro lugar: cor, tipografia, espaçamento, raio, sombra.

Por isso, a ordem que funcionou para mim foi:

  • Primitivos a partir do manual de marca. Peguei as cores principais do manual da empresa e desdobrei cada uma numa escala de 100 a 900. Na maioria dos casos, o 500 é o valor base, o que bate com a cor oficial da marca.
  • Semânticos a partir dos primitivos. Em cima dessa escala criei tokens com significado: background, text, stroke e assim por diante. Cada um já nasce com os estados default, hover e pressed definidos.
  • Componentes que só consomem semânticos, nunca valores soltos.

Definir os estados no token, e não no componente, foi a decisão que mais acelerou o trabalho depois. Quem desenha uma interface nova não precisa escolher qual tom usar no hover: a resposta já está no sistema.

A mesma lógica valeu para grids, espaçamentos e tipografia, separados entre desktop e mobile. No Figma, organizei isso em modos de variáveis, de forma que, ao trocar o modo de um frame, tamanhos de texto, espaçamentos e grid se ajustam sozinhos ao padrão que definimos. A regra que passei a seguir é simples: se um componente tem um valor digitado à mão, ele está errado.

O ganho aparece depois. Quando uma cor muda, ela muda em um lugar só. E quando você conversa com o dev, os dois falam a mesma língua: “usa o token background-base-hover” em vez de “usa aquele cinza claro”.

3. Organização: o novo precisa conviver com o antigo

Nenhum design system nasce num vácuo. Enquanto você constrói, o time continua entregando telas com os componentes antigos. Se o novo arquivo simplesmente substituir o velho, você quebra o trabalho de todo mundo.

A solução que adotei foi manter os dois lado a lado, com sinalização explícita no nome:

  • (new): componentes do DS, ligados às foundations, que devem ser usados em projetos novos.
  • (old): componentes legados, mantidos para quem ainda não migrou.

Parece simples, mas resolve três problemas: ninguém perde o que já usa, fica óbvio o que é o caminho recomendado e a migração vira algo visível e mensurável.

O time reagiu bem, mas por vezes a vontade de atualizar os componentes e variáveis para os novos era muito grande e acabou gerando atrito com os devs dos produtos que ainda não haviam sido migrados, causando um retrabalho para voltar aos componentes OLDs até que a migração para o novo DS fosse autorizada.

A lição: deixar os dois convivendo no arquivo não basta. É preciso deixar claro quais produtos já podem usar o novo, tendo conversas com os times e alinhamentos constantes com a gestão, para que pudéssemos priorizar a adoção pelos times e eu conseguir fazer, individualmente, a passagem de conhecimento.

Outras regras de organização que valeram a pena:

  • Uma seção por estado de maturidade, não só por tipo de componente. O que está pronto fica separado do que está em construção.
  • Nomes que o dev reconhece. Se no código o componente se chama Modal Dialog, no Figma também, todos os nomes devem estar idênticos.
  • Propriedades em vez de variantes infinitas. Booleanos e propriedades de texto reduzem o número de variantes e deixam o painel do designer mais limpo.
  • Uma página de capa com instruções. O primeiro contato com o arquivo deve dizer o que usar e o que ignorar.

Na prática, isso também significou usar a funcionalidade de slots do Figma, para que os designers pudessem encaixar diferentes componentes dentro dos cards mantendo espaçamentos, raios e cores consistentes em todo o Design System.

4. Documentação que as pessoas realmente usam

Documentação de design system costuma morrer por excesso, não por falta. Páginas longas, bonitas e que ninguém abre. O que aprendi é que cada componente precisa responder a poucas perguntas, sempre na mesma ordem.

A linha “quando não usar” é a mais valiosa e a mais esquecida. É ela que evita o modal usado como página ou a tag usada como botão.

Duas decisões que me pouparam tempo:

  • Dois níveis de documentação. No Figma, ao lado de cada componente, fica o essencial para quem está desenhando. No zeroheight fica a documentação completa, a referência oficial para designers, devs e outras áreas. Quem só precisa tirar uma dúvida rápida não sai do Figma. Quem precisa entender o sistema tem um lugar só para consultar.
  • Escrever com o produto na cabeça. Exemplos genéricos (“use para ações primárias”) dão menos contexto. Exemplos do produto (“use para confirmar o envio de uma solicitação”) são melhores para a utilização.

5. Handoff é parceria, não entrega

O maior aprendizado de handoff foi parar de pensar nele como um momento. Handoff bom é uma conversa contínua com quem vai codar. No meu caso, trabalhei com um desenvolvedor muito experiente desde o início, e isso mudou o projeto. O OutSystems tinha limitações, mas conseguimos contornar todas, porque elas apareciam na conversa enquanto o componente ainda estava sendo desenhado.

O que funcionou:

  • Envolver o dev antes do componente ficar pronto. Uma revisão de 15 minutos no rascunho evita um componente impossível de implementar na plataforma.
  • Combinar a nomenclatura uma vez. Nomes de componentes, propriedades e tokens iguais no Figma e no código.
  • Prazo por componente, não pelo sistema inteiro. Entregar em lotes deixa o DS em uso mais cedo e gera feedback real.
  • Especificar estados, não só o visual padrão. Foco, erro, carregamento e vazio são onde o retrabalho mora.

Um checklist simples que eu uso antes de considerar um componente pronto para dev:

  • Usa apenas tokens semânticos
  • Todos os estados desenhados
  • Nome igual ao do código
  • Comportamento responsivo descrito
  • Critérios de acessibilidade anotados
  • Revisado com o dev

6. Onde a IA entrou (e onde não entrou)

Usei IA, principalmente o Claude, como um par de trabalho para as partes repetitivas e para as partes em que eu precisava de um segundo olhar. As decisões de design continuaram sendo minhas. O que mudou foi o tempo gasto no que vem em volta delas.

Uma IA para escrever o pedido, outra para executar. Usei o ChatGPT para estruturar os prompts que eu depois levava ao Claude. Separar “pensar no pedido” de “executar o pedido” deixou as respostas muito mais precisas, principalmente em tarefas longas e cheias de regras.

Construir e documentar tokens. Foi onde o Claude mais me ajudou. Tokens são trabalho de muita consistência e pouca criatividade: nomear, organizar em coleções, descrever quando usar cada um. Com um prompt bem estruturado, ele propunha a estrutura e os textos, e eu revisava e ajustava.

Testar os componentes em tela. Usei o Figma Make, o Stitch do Google e o Claude, conectado ao Figma via MCP, para montar telas com os componentes que eu tinha acabado de construir. É um teste de estresse: quando uma tela pede algo que o sistema não tem, ou quando um componente se comporta mal fora do contexto em que foi desenhado, o problema aparece antes de chegar no time.

Escrever a documentação no Zeroheight. O Claude também me ajudou a montar as páginas de documentação, seguindo a estrutura fixa da seção anterior. Sair da página em branco deixou de ser o gargalo.

O que aprendi sobre usar IA nesse contexto:

  • Contexto é tudo. Instruções como “use só os componentes (new), ignore os (old)” mudam completamente o resultado. Quanto mais regras do seu DS você explicita, melhor a resposta.
  • Use para ler e rascunhar, não para decidir. A IA é ótima em levantar, organizar e propor. Quem conhece o usuário, o produto e as restrições técnicas é você.
  • Revise tudo. Valores, nomes e specs gerados precisam ser conferidos no arquivo. Um token errado na documentação é pior que nenhum.
  • Cuidado com dados sensíveis. Veja o que a sua empresa permite compartilhar com ferramentas de IA antes de conectar arquivos internos.

7. O que eu faria diferente

Olhando para trás, eu mudaria duas coisas. Nenhuma delas é sobre componentes.

Usar ainda mais IA, e desde o começo. Eu trouxe a IA para o processo aos poucos, conforme ia descobrindo onde ela ajudava. Se começasse hoje, usaria desde o inventário até a documentação, em vez de reservar só para as etapas mais repetitivas. Testaria mais exaustivamente (e mais rapidamente) as possibilidades da IA me auxiliar em todo processo — mas também houve um aprendizado muito grande com toda essa pesquisa de uso, em um ambiente que não pude me dedicar inteiramente a esses estudos; entendo que o ritmo de aprendizado foi o melhor possível.

💡 Não se culpe por não saber tudo. Pesquise, anote, entenda e ponha em prática: é a melhor forma de se habituar com as mudanças tão rápidas em relação à IA.

Comunicar além dos designers. Eu mantinha os outros designers atualizados sobre cada novidade, mas falava menos com stakeholders e gestores. Esse é o público que decide se o design system continua recebendo tempo e prioridade. Hoje eu comunicaria cada melhoria implementada para eles também, de forma curta, objetiva e regular.

Design system é um trabalho que acontece nos bastidores. Se ninguém vê o que está sendo feito, fica fácil ele perder espaço para as demandas mais urgentes. Mostrar o trabalho de forma clara e objetiva não é vaidade: é o que garante a continuidade dele.

Fechamento

Um design system não é um arquivo de componentes. É um acordo entre pessoas sobre como construir produto, e esse acordo só se sustenta se for fácil de encontrar, fácil de entender e fácil de implementar.

Se eu tivesse que resumir para quem está começando: comece pelo inventário, não pelo botão. O dev é um coautor, não destinatário. Use IA para tirar do caminho o trabalho repetitivo, e sobra tempo para as decisões que só você pode tomar. E mostre o que está fazendo, para além do time de design.

Se quiseres os prompts que usei para construir e documentar tokens e componentes, me chama para conversarmos. :)

Publicado originalmente no Medium: medium.com/@vitoriaasimon