Construindo um Design System escalável e confiável, do Figma ao código

Construindo um Design System escalável e confiável, do Figma ao código

Construindo um Design System escalável e confiável, do Figma ao código

Construindo um Design System escalável e confiável, do Figma ao código

Como usei automação com IA para levar tokens e componentes do Figma até o código de produção e reduzir em 16% as inconsistências de componentes
Como usei automação com IA para levar tokens e componentes do Figma até o código de produção e reduzir em 16% as inconsistências de componentes
Como usei automação com IA para levar tokens e componentes do Figma até o código de produção e reduzir em 16% as inconsistências de componentes

Ano

Ano

Ano

2026
2026
2026

Duração

Duração

Duração

3 semanas
3 semanas
3 semanas

Categoria

Categoria

Categoria

Design System
Design System
Design System

Minha função

Minha função

Minha função

Product Designer
Product Designer
Product Designer
Contexto
Contexto
Contexto
A Accion precisava de consistência visual em seus produtos. O Portal de Vendas B2B, os fluxos de agente de IA da Accion (AIDA) e o Portal do Cliente cresciam em paralelo, cada um resolvendo os próprios problemas de UI do seu jeito. O time de desenvolvimento já usava o Material Design do Google (MUI) como base, o que resolvia parte do trabalho de implementação, mas deixava a marca genérica e limitava o quanto o produto conseguia se diferenciar visualmente.

Para dar uma base sólida a esse crescimento, desenhei um Design System completo no Figma, desde a arquitetura de tokens em camadas até variáveis para temas com dezenas de componentes documentados.
A Accion precisava de consistência visual em seus produtos. O Portal de Vendas B2B, os fluxos de agente de IA da Accion (AIDA) e o Portal do Cliente cresciam em paralelo, cada um resolvendo os próprios problemas de UI do seu jeito. O time de desenvolvimento já usava o Material Design do Google (MUI) como base, o que resolvia parte do trabalho de implementação, mas deixava a marca genérica e limitava o quanto o produto conseguia se diferenciar visualmente.

Para dar uma base sólida a esse crescimento, desenhei um Design System completo no Figma, desde a arquitetura de tokens em camadas até variáveis para temas com dezenas de componentes documentados.
Problema
Problema
Problema
Ter o sistema pronto no Figma resolvia metade do problema. A outra metade era fazer ele existir no produto.
Quando propus a migração, a reação do time de desenvolvimento foi imediata: eles já tinham o MUI rodando, integrado e testado, e por isso reconstruir tudo do zero em outra biblioteca soava como retrabalho puro, sem ganho proporcional ao esforço. E eles tinham razão em desconfiar: um Design System que só existe como documentação bonita no Figma, e que exige que cada componente seja recriado manualmente em código, tende a nascer defasado e morrer rápido.

Mas o MUI puro também tinha um custo que não aparecia à primeira vista: para adaptar os componentes padrão à marca da Accion, cada squad fazia seus próprios ajustes de estilo em cima da lib, como um botão customizado no Portal de Vendas, outro ligeiramente diferente no Portal do Cliente, outro nos fluxos da AIDA. Nenhum desvio isolado parecia grave, mas o acúmulo criava exatamente o tipo de inconsistência que um Design System deveria evitar: múltiplas versões do "mesmo" componente, sem uma fonte única de verdade entre design e código.

Desde o início, a intenção não foi de "desenhar componentes", nem "ser mais rápido que o MUI", e sim reduzir a distância entre o Figma e o código a praticamente zero, para que adotar o novo sistema custasse menos do que continuar convivendo com as variações informais que o MUI, sozinho, não impedia.
Ter o sistema pronto no Figma resolvia metade do problema. A outra metade era fazer ele existir no produto.
Quando propus a migração, a reação do time de desenvolvimento foi imediata: eles já tinham o MUI rodando, integrado e testado, e por isso reconstruir tudo do zero em outra biblioteca soava como retrabalho puro, sem ganho proporcional ao esforço. E eles tinham razão em desconfiar: um Design System que só existe como documentação bonita no Figma, e que exige que cada componente seja recriado manualmente em código, tende a nascer defasado e morrer rápido.

Mas o MUI puro também tinha um custo que não aparecia à primeira vista: para adaptar os componentes padrão à marca da Accion, cada squad fazia seus próprios ajustes de estilo em cima da lib, como um botão customizado no Portal de Vendas, outro ligeiramente diferente no Portal do Cliente, outro nos fluxos da AIDA. Nenhum desvio isolado parecia grave, mas o acúmulo criava exatamente o tipo de inconsistência que um Design System deveria evitar: múltiplas versões do "mesmo" componente, sem uma fonte única de verdade entre design e código.

Desde o início, a intenção não foi de "desenhar componentes", nem "ser mais rápido que o MUI", e sim reduzir a distância entre o Figma e o código a praticamente zero, para que adotar o novo sistema custasse menos do que continuar convivendo com as variações informais que o MUI, sozinho, não impedia.
O Processo
O Processo
O Processo

Repensando o problema para solucioná-lo através de automação

Repensando o problema para solucioná-lo através de automação

Em vez de pedir para o time recriar cada componente manualmente, busquei formas de usar IA para gerar boa parte da ponte entre design e código. Usando o Cursor, converti a documentação de tokens e componentes do Figma em componentes React funcionais, fiéis às variantes, estados e tokens definidos no design, reduzindo a maior parte do trabalho manual de implementação que normalmente recai sobre o time de front-end.
Em vez de pedir para o time recriar cada componente manualmente, busquei formas de usar IA para gerar boa parte da ponte entre design e código. Usando o Cursor, converti a documentação de tokens e componentes do Figma em componentes React funcionais, fiéis às variantes, estados e tokens definidos no design, reduzindo a maior parte do trabalho manual de implementação que normalmente recai sobre o time de front-end.

Mantendo os mesmos nomes do Material Design (MUI)

Mantendo os mesmos nomes do Material Design (MUI)

Para reduzir ainda mais o atrito da migração, nomeei os componentes do Design System com os mesmos nomes já usados no MUI (Button, TextField, Modal, etc.). Na prática, boa parte da adoção virou uma troca de importação (de @mui/material para @accion-ds) em vez de reescrever chamadas de componente ou reaprender uma API nova. Isso removeu uma camada inteira de resistência: o time não precisava decorar nomes novos para algo que já sabia usar.
Para reduzir ainda mais o atrito da migração, nomeei os componentes do Design System com os mesmos nomes já usados no MUI (Button, TextField, Modal, etc.). Na prática, boa parte da adoção virou uma troca de importação (de @mui/material para @accion-ds) em vez de reescrever chamadas de componente ou reaprender uma API nova. Isso removeu uma camada inteira de resistência: o time não precisava decorar nomes novos para algo que já sabia usar.

Publicando onde os desenvolvedores já trabalham

Publicando onde os desenvolvedores já trabalham

Subi o pacote no GitHub e documentei os componentes no Storybook, para que o time pudesse visualizar, testar e adotar cada peça isoladamente sem precisar migrar o produto inteiro de uma vez. Isso transformou a migração de "projeto arriscado" em algo incremental, componente por componente.
Subi o pacote no GitHub e documentei os componentes no Storybook, para que o time pudesse visualizar, testar e adotar cada peça isoladamente sem precisar migrar o produto inteiro de uma vez. Isso transformou a migração de "projeto arriscado" em algo incremental, componente por componente.

Escrevendo o sistema para ser lido por máquina, não só por pessoas

Escrevendo o sistema para ser lido por máquina, não só por pessoas

Em vez de pedir para o time recriar cada componente manualmente, busquei formas de usar IA para gerar boa parte da ponte entre design e código. Usando o Cursor, converti a documentação de tokens e componentes do Figma em componentes React funcionais, fiéis às variantes, estados e tokens definidos no design, reduzindo a maior parte do trabalho manual de implementação que normalmente recai sobre o time de front-end.

Documentei as regras do Design System em um markdown design.md utilizando contextos normativos e descritivos, como cada coisa é (qual azul é o azul, quanto vale cada unidade de espaçamento, quais tokens existem, etc.) e o que não pode acontecer, mesmo que o agente encontre um caminho mais bonito ou mais rápido. Essa escolha existe porque quem lê esse documento na maioria das vezes acaba sendo uma IA (o próprio Cursor) gerando componentes a partir dele. Regras ambíguas ou "dicas de bom senso" não funcionam nesse contexto, já que o documento precisava eliminar interpretação, funcionando quase como uma especificação técnica em vez de um guia inspiracional.
Em vez de pedir para o time recriar cada componente manualmente, busquei formas de usar IA para gerar boa parte da ponte entre design e código. Usando o Cursor, converti a documentação de tokens e componentes do Figma em componentes React funcionais, fiéis às variantes, estados e tokens definidos no design, reduzindo a maior parte do trabalho manual de implementação que normalmente recai sobre o time de front-end.

Documentei as regras do Design System em um markdown design.md utilizando contextos normativos e descritivos, como cada coisa é (qual azul é o azul, quanto vale cada unidade de espaçamento, quais tokens existem, etc.) e o que não pode acontecer, mesmo que o agente encontre um caminho mais bonito ou mais rápido. Essa escolha existe porque quem lê esse documento na maioria das vezes acaba sendo uma IA (o próprio Cursor) gerando componentes a partir dele. Regras ambíguas ou "dicas de bom senso" não funcionam nesse contexto, já que o documento precisava eliminar interpretação, funcionando quase como uma especificação técnica em vez de um guia inspiracional.
Solução
Solução
Solução
O resultado foi um Design System com três camadas trabalhando juntas
O resultado foi um Design System com três camadas trabalhando juntas
Tokens estruturados no Figma
Tokens estruturados no Figma
Tokens estruturados no Figma
Variáveis organizadas em primitivos, marca e componentes, permitindo temas e ajustes globais sem quebrar nada nas pontas.
Variáveis organizadas em primitivos, marca e componentes, permitindo temas e ajustes globais sem quebrar nada nas pontas.
Variáveis organizadas em primitivos, marca e componentes, permitindo temas e ajustes globais sem quebrar nada nas pontas.
Código gerado e publicado
Código gerado e publicado
Código gerado e publicado
O mesmo sistema, agora como pacote de componentes React no GitHub, documentado no Storybook, pronto para ser instalado e usado como qualquer outra biblioteca.
O mesmo sistema, agora como pacote de componentes React no GitHub, documentado no Storybook, pronto para ser instalado e usado como qualquer outra biblioteca.
O mesmo sistema, agora como pacote de componentes React no GitHub, documentado no Storybook, pronto para ser instalado e usado como qualquer outra biblioteca.
Diretrizes de escrita
Diretrizes de escrita
Diretrizes de escrita
Padrões de microcopy e tom de voz documentados junto aos componentes, para que texto e interface evoluíssem como uma coisa só.
Padrões de microcopy e tom de voz documentados junto aos componentes, para que texto e interface evoluíssem como uma coisa só.
Padrões de microcopy e tom de voz documentados junto aos componentes, para que texto e interface evoluíssem como uma coisa só.
Com o sistema publicado, também passei a usá-lo como ferramenta de prototipação: o Portal do Cliente, por exemplo, foi prototipado com os componentes do próprio Design System, o que tornou o processo de validação de ideias mais rápido, já nascendo com os padrões visuais e de interação corretos, sem retrabalho de adaptação depois.
Com o sistema publicado, também passei a usá-lo como ferramenta de prototipação: o Portal do Cliente, por exemplo, foi prototipado com os componentes do próprio Design System, o que tornou o processo de validação de ideias mais rápido, já nascendo com os padrões visuais e de interação corretos, sem retrabalho de adaptação depois.
O resultado
O resultado
O resultado
16% de redução nas inconsistências de componentes
16% de redução nas inconsistências de componentes
Comparando o número de variações informais de estilo (botões, inputs, badges customizados pelos devs) antes e depois da adoção do pacote publicado.
Comparando o número de variações informais de estilo (botões, inputs, badges customizados pelos devs) antes e depois da adoção do pacote publicado.
Comparando o número de variações informais de estilo (botões, inputs, badges customizados pelos devs) antes e depois da adoção do pacote publicado.
Fonte única de verdade entre design e código
Fonte única de verdade entre design e código
Fonte única de verdade entre design e código
Os componentes deixaram de ser "recriados" pelos desenvolvedores e passaram a ser importados do mesmo pacote, eliminando divergência por definição, não por acordo verbal entre times.
Os componentes deixaram de ser "recriados" pelos desenvolvedores e passaram a ser importados do mesmo pacote, eliminando divergência por definição, não por acordo verbal entre times.
Os componentes deixaram de ser "recriados" pelos desenvolvedores e passaram a ser importados do mesmo pacote, eliminando divergência por definição, não por acordo verbal entre times.
32% de aceleração na prototipação de novos produtos
32% de aceleração na prototipação de novos produtos
32% de aceleração na prototipação de novos produtos
Com os componentes já prontos, eu como designer, conseguia montar boa parte das telas direto no Figma e usar IA para transformá-las em algo funcional, reduzindo a dependência de um ciclo completo de handoff para validar uma ideia nova (como feito no Portal do Cliente).
Com os componentes já prontos, eu como designer, conseguia montar boa parte das telas direto no Figma e usar IA para transformá-las em algo funcional, reduzindo a dependência de um ciclo completo de handoff para validar uma ideia nova (como feito no Portal do Cliente).
Com os componentes já prontos, eu como designer, conseguia montar boa parte das telas direto no Figma e usar IA para transformá-las em algo funcional, reduzindo a dependência de um ciclo completo de handoff para validar uma ideia nova (como feito no Portal do Cliente).
Aprendizados desse projeto
Aprendizados desse projeto
Aprendizados desse projeto
Design System não se mede pelo número de componentes, e sim pela distância entre Figma e produção
Design System não se mede pelo número de componentes, e sim pela distância entre Figma e produção
Design System não se mede pelo número de componentes, e sim pela distância entre Figma e produção
Um sistema robusto no Figma que não chega ao código continua sendo documentação e o valor real aparece quando o time de desenvolvimento sente que usar o sistema é mais rápido do que não usar.
Escrever para IA exige um tipo de precisão diferente de escrever para pessoas
Escrever para IA exige um tipo de precisão diferente de escrever para pessoas
Escrever para IA exige um tipo de precisão diferente de escrever para pessoas
Um guia de estilo tradicional tolera ambiguidade porque humanos preenchem lacunas com bom senso; um documento lido por um agente de IA não pode depender disso. Cada regra precisa ser explícita o suficiente para sobreviver mesmo quando o agente "acha" que encontrou uma solução mais elegante.
Adoção gradual reduz resistência
Adoção gradual reduz resistência
Adoção gradual reduz resistência
Um sistema robusto no Figma que não chega ao código continua sendo documentação e o valor real aparece quando o time de desenvolvimento sente que usar o sistema é mais rápido do que não usar.

Boas experiências começam com boas perguntas

oi@bryanpeace.com

Boas experiências começam com boas perguntas

oi@bryanpeace.com

Boas experiências começam com boas perguntas

oi@bryanpeace.com

Boas experiências começam com boas perguntas

oi@bryanpeace.com