18 de novembro de 2026
Antes do primeiro componente: aprendizados de um design system construído 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
