Tokens com aplicação variável
Cores, estados, espaçamentos e estilos existiam, mas precisavam de uma aplicação mais previsível entre contextos.
Case study
Design System para escala: reconstruindo a base da plataforma
Quando o Design System cresce sem governança suficiente, cada nova tela volta a exigir decisões que deveriam ser compartilhadas.
Uma frente de reorganização completa do Design System da Monetizze, revisando tokens, variáveis, componentes e padrões de interface para transformar uma biblioteca em evolução em uma base mais consistente, implementável e alinhada ao front-end com apoio estrutural do shadcn.
01Tokens
02Variables
03Components
04Layouts
05Flows
Biblioteca inteira revisadaTokens e variáveisComponentes unificadosLight/Dark modeshadcn como referênciaPlataforma Monetizze
02
O Design System existia, mas precisava evoluir para sustentar escala
A Monetizze já possuía uma biblioteca de Design System, construída ao longo de diferentes ciclos de contribuição e necessidades da plataforma. Com o crescimento dos fluxos, a base passou a acumular variações, exceções e decisões recorrentes que precisavam de mais governança. Na prática, tokens, variáveis, componentes e layouts ainda exigiam ajustes manuais para manter consistência entre design e implementação.
03
O desafio ia além do visual. Era operacional.
A inconsistência aparecia na interface, mas a oportunidade de melhoria estava na fundação: tokens, variáveis, componentes, estados e padrões de uso.
Componentes com variações acumuladas
Componentes semelhantes haviam evoluído com estruturas e comportamentos diferentes, exigindo revisão para unificação.
Variáveis pedindo mais governança
A base precisava de uma lógica mais clara para sustentar temas, estados e reaproveitamento entre fluxos.
Layouts com decisões recorrentes
Novas telas ainda dependiam de ajustes frequentes de grid, espaçamento, hierarquia e responsividade.
Ponte entre Figma e código
O handoff podia ganhar precisão com uma biblioteca visual mais alinhada à estrutura de implementação.
04
Hipótese
Se a biblioteca fosse reorganizada a partir da fundação — tokens, variáveis, componentes e estados — e alinhada a uma referência próxima do código, o time teria mais consistência, menos decisões repetidas e mais velocidade para desenhar e implementar interfaces da plataforma.
05
shadcn como referência estrutural, não como estética pronta
A decisão de aproximar o Design System do shadcn partiu da necessidade de dar mais precisão à ponte entre UX/UI e front-end. A ideia não era importar uma estética pronta, mas usar uma estrutura de componentes mais próxima da implementação para revisar variantes, estados, temas e padrões de uso com mais previsibilidade.
Mais próximo do código
Componentes pensados com estrutura, variações e comportamento mais próximos da implementação.
Mais previsível para o time
Estados, temas e padrões deixam de depender apenas de interpretação visual.
Mais flexível para a plataforma
A base podia ser adaptada à identidade do produto sem perder consistência.
Mais claro no handoff
Design e front-end passam a discutir a mesma estrutura, não apenas a aparência final.
06
Como reconstruí a base
01
Auditoria da biblioteca
Revisão da estrutura existente para mapear variações em tokens, componentes, variáveis, estados e padrões de layout.
02
Reconstrução da fundação
Reorganização de tokens, variáveis, temas, cores, tipografia, radius, espaçamentos e estados para criar mais previsibilidade.
03
Revisão componente por componente
Revisão da biblioteca inteira, tocando cada componente para alinhar estrutura, variantes e regras de uso.
04
Precisão com shadcn
Uso do shadcn como referência de estrutura e implementação para aproximar o Design System da realidade do front-end.
05
Estados e temas
Revisão de default, hover, focus, disabled, loading, error, light mode e dark mode para tornar comportamentos mais consistentes.
06
Documentação e handoff
Organização dos padrões para reduzir interpretação manual e evitar que cada novo fluxo dependesse das mesmas decisões de base.
07
Laboratório de componentes
Uma reconstrução conceitual da lógica trabalhada na biblioteca: tokens, temas, componentes, variações e estados conectados em uma base mais próxima da implementação.
Preview conceitual
Dark
Altere componente, estado, tema e variante para visualizar como decisões de token afetam a interface.
Button · Primary · Default · MD · Dark
Estado
Componente
Estilo
Tokens conectadosValores principais relacionados ao estado e variante selecionados.
background
228 45% 10%foreground
225 26% 92%primary
#0011FEborder
228 35% 25%radius
0.7remprimary hover
#0014E6primary pressed
#000FD1focus ring
rgba(0, 17, 254, 0.35)Componente
Componente
Estado
Estado
Estilo
Tema
Variante
Tamanho
Tokens conectadosValores principais relacionados ao estado e variante selecionados.
background
228 45% 10%foreground
225 26% 92%primary
#0011FEborder
228 35% 25%radius
0.7remprimary hover
#0014E6primary pressed
#000FD1focus ring
rgba(0, 17, 254, 0.35)Artefato reconstruído para apresentação. A estrutura preserva o raciocínio de Design System sem expor arquivos internos, dados sensíveis ou documentação proprietária.
08
Da fundação à interface
O trabalho começou abaixo da tela final. Antes de redesenhar componentes, era preciso reorganizar a base que sustentava cor, tema, espaçamento, estado e comportamento.
Tokens
Definem os valores fundamentais de cor, tipografia, espaçamento, radius e estados.
Variáveis
Conectam tokens a temas, contextos e modos de uso.
Componentes
Transformam decisões recorrentes em estruturas reutilizáveis.
Layouts
Organizam hierarquia, espaçamento e responsividade.
Fluxos
Aplicam a base em jornadas reais da plataforma.
09
De biblioteca em evolução a base implementável
Antes
- Tokens com aplicação variável entre contextos.
- Componentes semelhantes com estruturas diferentes.
- Layouts ainda dependentes de decisões recorrentes.
- Estados que precisavam de mais previsibilidade.
- Handoff com espaço para interpretação manual.
Depois
- Tokens e variáveis reorganizados.
- Componentes alinhados em estrutura e uso.
- Temas light/dark mais previsíveis.
- Estados documentados.
- Base visual mais próxima da implementação.
10
Trade-offs
Reconstruir um Design System inteiro exigia equilibrar velocidade, consistência, flexibilidade e manutenção.
Padronização vs flexibilidade
O sistema precisava unificar decisões sem impedir necessidades específicas da plataforma.
Velocidade vs identidade visual
O shadcn acelerava a precisão estrutural, mas exigia curadoria para não deixar o produto genérico.
Cobertura total vs manutenção
Revisar a biblioteca inteira exigia cuidado para não criar complexidade desnecessária.
Figma vs código real
O objetivo não era apenas desenhar componentes bonitos, mas criar padrões implementáveis.
Light/Dark mode
Não bastava inverter cores; era preciso preservar contraste, hierarquia e estados.
11
Resultado observado
A frente ajudou a transformar o Design System em uma base mais confiável para a plataforma, reduzindo ambiguidades no handoff, melhorando consistência entre fluxos e criando uma estrutura mais próxima da implementação para UX/UI e front-end trabalharem com mais precisão.
Menos decisões repetidas
Handoff mais claro
Componentes mais previsíveis
Base mais próxima do front-end
Mais consistência entre fluxos
12
O que ficou como aprendizado
- Design System não é apenas biblioteca visual; é infraestrutura de decisão.
- Tokens só geram escala quando são aplicados de forma consistente.
- Componentes precisam carregar estados, variações e regras de uso, não apenas aparência.
- Aproximar Figma e código reduz interpretação manual no handoff.
- Referências como shadcn aceleram a base, mas precisam de curadoria para preservar identidade e contexto.
13
Vamos conversar sobre sistemas que escalam?
Design systems, tokens, componentes e documentação são partes invisíveis da experiência que reduzem ruído, aceleram times e sustentam produtos mais consistentes.