Design system Braip — de biblioteca a sistema

Contexto

A Braip é uma plataforma de vendas e afiliados, e o design system existe para sustentar um web app que roda em modo claro e escuro com paridade real — não como cortesia visual, mas porque parte considerável da operação acontece no escuro.

O time de design é pequeno e a engenharia consome o Figma diretamente: o que está nomeado no arquivo é o que chega no código. Isso torna a nomenclatura de variável uma decisão de produto, não de organização interna.

A restrição que moldou todo o trabalho: o sistema estava em produção e não havia janela para refazê-lo do zero. Tudo foi feito sobre a biblioteca viva, com componentes sendo instanciados em arquivos de outras pessoas durante a mudança.

O problema

O sistema não tinha um problema de aparência. Tinha um problema de nome.

Sufixos numéricos sem papel definido. O grupo State da collection ❖ Color expunha cada cor em quatro tiers — 01, 02, 03, 04. O número descrevia luminosidade, nunca função. State/Purple/03 não responde à única pergunta que importa na hora de desenhar: posso usar isso como texto? Na prática, cada pessoa escolhia um tier diferente para a mesma função, e a divergência só aparecia quando duas telas ficavam lado a lado.

Contraste nunca medido. As combinações de texto colorido sobre fundo tint eram escolhidas a olho. No modo escuro, onde o fundo do chip se mistura ao canvas #0B0B0E, "parece legível" e "é legível" não são a mesma coisa — e ninguém tinha o número para saber qual dos dois estava acontecendo.

Motion como valor avulso. Hover, sheet e toast tinham duração definida tela a tela. Não existia escala, não existia vocabulário e, portanto, não existia como revisar uma micro-interação a não ser por opinião.

Meu papel

Fui o dono da trilha de tokens, contraste e documentação dentro do time de design, sob o épico de design system TI-2036. Isso cobre a arquitetura de nomes das variáveis, a auditoria de contraste, a escala de motion e as specs de handoff.

O que não é meu: os componentes de produto em si, desenhados pelo time ao longo do tempo, e a implementação em código do consumo desses tokens. Meu trabalho foi dar a esses componentes uma base que se explicasse sozinha.

Processo

Comecei auditando a collection ❖ Color e, em vez de propor uma convenção do zero, fui ler o uso real. Inspecionei como os componentes Tags e Chips já consumiam os tiers: na variante Solid, o container usava o tier 03 e o texto ficava branco; na Minimalist, o container usava 01/02 e o texto usava 03. Havia uma convenção implícita ali, funcionando, sem nome.

Com o padrão implícito mapeado, comparei com o que design systems maduros fazem para escalas de estado — Ant Design, Atlassian, Polaris e IBM Carbon convergem para a mesma sequência de papéis: fundo, contorno, ícone, texto. A convenção da Braip já era essa; faltava dizê-la em voz alta.

A partir daí: renomeação sem tocar em valor, medição de contraste sobre a escala renomeada, correção dos pares que não passavam e, por último, a extensão da mesma lógica de "nome que diz a função" para motion.

Cada etapa virou spec e plano versionados antes da execução — 20 specs e 28 planos de design entre 3 e 24 de julho de 2026. O plano existe menos para lembrar o que fazer e mais para deixar registrado o que foi descartado.

Decisões-chave

Decisão 1 — Papel semântico em vez de escala numérica

Contexto: State/<Cor>/01–04, em nove cores. O número indicava luminosidade, não função.

Alternativa descartada: manter os números e publicar uma legenda explicando o mapeamento de cada tier.

Por que esta: legenda é documentação que ninguém abre no meio de um handoff. O nome, ao contrário, viaja junto com o token — aparece no inspector, aparece no código, aparece na conversa. E adotar a sequência que Ant Design, Atlassian, Polaris e Carbon já usam reduz o custo de entrada de quem chega de outro sistema: a pessoa não precisa aprender a Braip, só reconhecer o padrão.

Decisão 2 — Renomear sem tocar em valor

Contexto: havia a tentação de corrigir cor e nome na mesma passada, já que o arquivo estava aberto de qualquer forma.

Alternativa descartada: rename e rebind de valores num único movimento.

Por que esta: separar as duas operações torna cada uma verificável. Se nada muda visualmente depois do rename, o rename está certo — qualquer diferença de pixel seria bug, não intenção. O ajuste cromático veio depois, guiado pelo relatório de contraste, e pôde ser avaliado isoladamente porque a camada de nomes já estava estável.

Decisão 3 — Legado desativado por documentação, não por deleção

Contexto: a collection Motion carregava uma escala antiga, value/duration/100 a 600, sem vínculo com os tokens semânticos novos.

Alternativa descartada: apagar as variáveis legadas junto com a publicação da nova escala.

Por que esta: apagar variável em biblioteca viva quebra instância em arquivo que não é seu, e a pessoa afetada descobre pelo estrago. Marcar explicitamente como "não usar" na documentação de referência interrompe a adoção sem quebrar ninguém; a remoção fica para quando o consumo chegar a zero.

Solução

A base final da Braip são 839 tokens em sete categorias — cor, cor semântica, primitivos, tipografia, espaçamento, layout e responsividade.

Cor de estado. Nove cores (Neutral, Purple, Green, Blue, Pink, Orange, Red, Yellow e Off) expostas por papel, não por índice: background → border → icon → text. São 35 variáveis renomeadas, em dois modos, sem nenhuma alteração de valor no processo. Off é a exceção documentada: tem só três tiers, porque nunca precisou de um nível de ênfase.

Contraste. Chips e Tags auditados em WCAG 2.0 AA nas nove cores, nos dois modos, com a razão de cada par registrada em tabela. Os pares que não alcançavam 4.5:1 foram corrigidos antes da publicação, não depois do relato de alguém.

Motion. Cinco tokens de duração (instant, fast, base, slow, slower) e três de easing (standard, enter, exit), cada um com guideline de quando usar — fast para micro-hover, base para toast, slow para sheet; enter para elemento que aparece, exit para elemento que sai, standard para transição neutra. A escala foi aplicada em três componentes de referência: Sheet, Toast e o hover do Button.

Toda a escala vive documentada na página Foundations do arquivo, com preview animável — a documentação é o próprio arquivo de trabalho, não um PDF paralelo que envelhece sozinho.

Resultado

O token passou a se explicar no handoff. Perguntar "qual tier eu uso aqui?" deixou de fazer sentido, porque a pergunta já está respondida no nome: se é texto, use text.

Contraste virou critério verificável em vez de opinião. Existe uma tabela com a razão medida de cada combinação de Chips e Tags, nas nove cores, nos dois modos — e o argumento numa revisão de design deixou de ser "acho que está claro demais" para ser uma linha dessa tabela.

Motion virou vocabulário compartilhado. Discutir se um sheet deve usar slow é uma conversa produtiva; discutir se deve usar 320 ou 340 milissegundos não é.

E o sistema absorveu tudo isso sem quebrar arquivo de ninguém — o legado saiu de circulação por documentação, no ritmo em que o consumo caiu.

O que eu faria diferente

Inverti a ordem. Renomeei antes de medir contraste, e o resultado foi ter que voltar na escala já renomeada para corrigir os pares que não passavam — o relatório final carrega marcas de "corrigido" que não existiriam se a medição tivesse vindo primeiro. Medir é barato; renomear duas vezes, não.

E tratei a evidência visual como etapa posterior à execução. Vários planos ficaram com a captura de tela pendente depois da mudança já aplicada, o que significa que parte do "antes" se perdeu. Documentar não é o passo seguinte ao trabalho — é parte dele, e quando fica para depois, normalmente não acontece.