Arquitetura com escala: construindo tokens em um Design System ativo

Experiência e aprendizados no desenvolvimento de uma arquitetura avançada de Design Tokens para um Design System com alta adoção.

Exemplo de aplicação de diversos níveis de tokens

Introdução

Assim como nós estamos em constante evolução, muitas coisas que fazem parte do nosso dia a dia também estão. Recentemente tive a oportunidade de me desafiar aprendendo uma nova habilidade e colocar em prática para evoluir nosso Design System do Asaas, o Atlas.

Em 2025 tivemos diversos desafios, sendo um deles a necessidade de evoluirmos os Design Tokens da nossa biblioteca para o próximo nível. O objetivo era prepará-la para se tornar mais escalável e flexível, acompanhando o ritmo de crescimento exponencial da empresa.

O maior desafio — comparável a uma cena de cinema onde os atores pulam de um trem em movimento — foi o de criar uma nova arquitetura de Design Tokens para nosso Design System que já está estabelecido, crescendo e sendo usado todos os dias.

Acima de tudo, o desafio foi garantir que a migração dos tokens antigos para a nova arquitetura gerasse o mínimo de impacto possível nas aplicações existentes.

Definindo a arquitetura

Após analisar nossos desafios, estabelecemos dois objetivos principais:

1. Criar uma arquitetura de tokens escalável, de fácil compreensão e alinhada com desenvolvimento;
2. Refatorar os componentes, introduzindo novos níveis de tokens específicos (Component Tokens) para aumentar a flexibilidade em especificações individuais.

Antes de começarmos as definições, analisamos a estrutura atual de tokens e como eles estavam aplicados em Design e em Desenvolvimento.

Mapeamos alguns itens para melhorias, como:

• A presença de apenas um nível de token tornava a aplicação muito abrangente e aumentava o risco de impacto em qualquer alteração;
• Muitas configurações eram específicas de componentes, resultando em aplicações distintas para o mesmo propósito em elementos diferentes;
• Falta de padronização para componentes similares;
• Divergência de nomenclatura entre o Figma e o código;
• Documentação simplificada, sem detalhamento de decisões críticas de aplicação, gerando dúvidas para novos usuários ou para quem buscava contexto.

Estrutura básica de tokens com 1 nível

Entendemos, assim, que a principal limitação era em relação a escalabilidade por causa do formato em que os tokens inicialmente foram construídos e, que já não atendia mais ao crescimento exponencial do Asaas. A mudança para uma arquitetura de tokens mais avançada era clara e urgente.

A arquitetura anterior possuía apenas o nível Foundations, que mesclava configurações básicas e fundacionais. Isso resultava em dificuldade e alto risco de impacto em qualquer alteração, além de exigir ajustes manuais em cada componente.

A importância de uma boa arquitetura de tokens, conforme Nathan Curtis, *reside em traduzir decisões de design de forma intencional e controlada, protegendo o sistema de mudanças imprevisíveis. Era justamente esse controle que buscamos implementar.*

Nossa estratégia, portanto, foi dividir os tokens em três camadas: Primitives, Foundations e Components. Essa divisão garante flexibilidade, controle e praticidade na manutenção e na padronização.

Entendendo a estrutura

Com os 3 níveis de Token estabelecidos, o próximo passo foi trazer clareza e organização sobre o comportamento de cada camada. Para isso, documentamos e fizemos muitas trocas entre o time de Design Ops e Desenvolvimento com o objetivo de facilitar na construção e migração da estrutura antiga para a nova por ambas as equipes.

A seguir, detalhamos o propósito e trouxemos exemplos de cada nível:

1. Primitives (Base)

Os tokens Primitives armazenam os valores brutos e agnósticos. Eles são a base, contendo as unidades de medida universais do Design System. É a partir deles que definimos os padrões iniciais para a escalabilidade controlada dos produtos.

Eles respondem a pergunta: “Quais valores fundamentais tenho disponíveis?”.

Exemplos de tokens do nível Primitives

2. Foundations (Semânticos)

Os tokens de Foundations aplicam contexto e significado à interface. São os tokens semânticos que definem o papel dos valores no Design System. Eles são alimentados pelos tokens Primitives.

Eles respondem à pergunta: “Qual é a função deste valor na interface?”.

Exemplos de tokens do nível Foundation

Foco em Acessibilidade: É neste nível que garantimos recursos essenciais de acessibilidade. Por exemplo, asseguramos um nível adequado de contraste, como o contraste mínimo de 4.5:1, conforme as diretrizes **WCAG**.

3. Components (Específicos)

Os tokens de Components sobrescrevem ou especificam um valor semântico para um componente específico ou um grupo relacionado. São usados para gerenciar detalhes que não podem ser padronizados globalmente e para cenários controlados de aplicação.

Eles respondem à pergunta: “Qual configuração quero ter mais controle ou ser mais específico?”

Nosso time decidiu aplicar essa camada de forma estratégica, sobretudo para agrupar configurações de componentes que exigem maior padronização e agrupamento, como os diferentes tipos de inputs e buttons.

Acompanhe alguns exemplos de tokens de componentes:

Exemplos de tokens do nível Components

Com essa estrutura, nosso Design System se tornou mais robusto, resiliente e preparado para receber mudanças de forma controlável, simplificada e escalável.

Estratégias de atualização

Com a nova estrutura pronta, organizamos e dividimos as tarefas de atualização para garantir o menor impacto possível. Mas para chegarmos até esse ponto, traçar uma estratégia e quebrar em pequenas tarefas foi crucial, nos ajudando a metrificar e acelerar o desenvolvimento.

Em 2025 fizemos grandes atualizações no Design System, incluindo a reestruturação de todos os componentes para atender ao nosso aplicativo. Foi nesse momento que preparamos o terreno para a nova arquitetura de tokens.

Inicialmente, criamos a camada de Components com tokens temporários. Isso nos permitiu migrar os tokens antigos, testar e aplicar melhorias pontuais, ganhando agilidade ao tratar cada componente individualmente (já que o foco principal ainda não era a arquitetura de tokens).

Após a conclusão da atualização dos componentes, iniciamos o processo de reestruturação da arquitetura dos tokens, começando pelos Primitives que não geraram impacto de imediato para nosso time de Produto. Na sequência, criamos os tokens de Foundations, que têm impacto direto nos componentes.

Com a estrutura criada e pronta, partimos para a etapa final de aplicação dos novos tokens em cada componente. Isso envolveu migrar os tokens antigos ou temporários para a camada Foundation mantendo na camada Components apenas os estritamente necessários para a padronização específica.

É importante ressaltar que os tokens antigos devem ser mantidos até que o processo de migração para a nova arquitetura seja concluído em Design e Desenvolvimento. Isso garante que nenhum componente seja quebrado ou perdido, especialmente considerando que estamos atualizando uma biblioteca com alta taxa de adoção.

Exemplo no Figma da divisão dos tokens antigos e novos

Aprendizados

Adotamos uma estrutura básica e consolidada de mercado, mas com decisões adaptadas buscando o equilíbrio entre as boas práticas do mercado e o que funciona no nosso contexto interno. É essencial analisar o cenário interno para definir o modelo ideal que funcione para o time (Design e Desenvolvimento) e a melhor forma de implementá-lo, mitigando problemas anteriores e garantindo uma evolução escalável pensando no futuro (que pode mudar amanhã).

Outro ponto crucial, principalmente no nível Foundations, foi a busca por clareza e simplicidade na nomenclatura. Este será o principal nível de tokens usado diariamente por designers e desenvolvedores de diferentes times. Por isso, trouxemos termos que transmitem a intenção e o significado diretamente na nomenclatura, agilizando o processo de busca e aplicação.

Meu maior aprendizado foi a colaboração constante com meu time, designers e desenvolvedores. Levamos em consideração cada debate e aprendizado, sempre com o foco na melhoria contínua do Design System e no crescimento do nosso trabalho.

A construção de um Design System é um ciclo contínuo. Além da atualização constante, os próximos passos incluem acompanhar a utilização pelo time para criar novos componentes/variações e explorar o potencial da IA em diversas aplicações, como o auxílio em documentações.

Até a próxima 👋🏽

Referências

• Naming Tokens in Design Systems
• Documentação da WCAG

Documentações de Design System:

• Material Design
• The design system guide
• Shopify
• Uber
• Atlassian

Estamos com oportunidades abertas! Confira nossas vagas e venha trabalhar com a gente.

Ah, e se você curtiu esse post, não deixe de bater palmas pra ele! 👏