O que a fundação de tokens escondeu: fechando o Marco 1 do Harness Design System

Read in english

Continuando a primeira semana de dedicação exclusiva do projeto, o trabalho foi todo no Marco 1, que a gente chamou de fundação técnica em tokens. Já contei nos artigos anteriores por que a gente começa por aí. Tokens são a menor unidade do sistema. Numa leitura de Atomic Design, eles são os átomos: vêm antes de qualquer componente, e tudo que a gente construir em cima herda o que eles definem. Arrumar essa base primeiro não é preciosismo, é o único jeito de não multiplicar o problema quando a IA entra em cima.

A estimativa era fechar tokens numa semana. Não fechou numa semana. E o motivo de não ter fechado é o que vale contar.

Tokens pareciam a parte simples

Criar e organizar token, no abstrato, parece a parte fácil do projeto. Cor, tipografia, espaçamento, raio de borda. Coisa pequena.

O que a gente foi descobrindo é que o problema não é criar o token. É migrar o sistema pra ele com segurança e atualizar isso em produção sem quebrar o que já está rodando. Isso deixa de ser tarefa de design e vira tarefa de sistema. Cada decisão pequena de token abre um leque de decisões de infraestrutura, de código e de processo que a gente não tinha dimensionado. Foi por isso que o Marco 1 acabou virando uma sequência de atividades bem maior do que a lista inicial, e a gente foi se realinhando quase todo dia pra dar conta do que ia aparecendo.

Três dessas surpresas merecem registro, porque são exatamente o tipo de coisa que ninguém conta.

A tipografia, que travou mais do que qualquer cor

O caso mais emblemático foi a tipografia. E foi o mais chato justamente por parecer trivial.

No Figma, itálico não é uma propriedade separada. O Figma funde peso e estilo numa string única — "regular itálico", "médium itálico" — então o peso que você escolhe já carrega o itálico embutido. Só que na exportação, quando o código vai consumir, isso precisa vir decomposto: de um lado o peso, de outro se é normal ou itálico. A gente tinha modelado o itálico dentro do campo de peso, e isso gerava token errado na saída.

Passamos um bom tempo tentando resolver isso dentro das variables. Criar um tipo pra normal e itálico, mapear peso a peso, tamanho a tamanho. Fui rodando, o Glauber foi testando, e a cada tentativa a organização ficava mais confusa em vez de mais limpa. Em algum momento a gente parou pra olhar como outros design systems tratam isso — Ant Design, Nitro — e a resposta foi um pouco humilhante: eles não tokenizam tipografia em variables. Resolvem nos estilos.

A decisão que fechou o assunto foi abandonar as variables de tipografia e consumir direto dos text styles do Figma. O estilo já carrega tudo junto — fonte, peso, itálico, line height, letter spacing — e é isso que o React e o Flutter passam a ler. Faço questão de dizer que essa não é uma vitória bonita. A gente mexeu, desfez, refez, e no fim tirou uma coisa que tinha construído. Isso quebrou o plugin de export, que tinha sido feito em cima do documento com todas as variables, e obrigou a atualizar ele.

Teve até um detalhe de nomenclatura no meio disso. A gente usava "medium" como nome de um tamanho de fonte, mas "medium" também é nome de peso. Pra uma LLM ler, essa ambiguidade é um convite ao erro. Trocamos por "Base", no estilo do Tailwind (text-base). Parece besteira. Nome de token importa mais do que parece quando quem lê é a máquina, e isso já tinha aparecido antes no projeto.

O bind, que a gente não conseguiu automatizar por fora

No artigo passado deixei o prompt de bind rodando via Figma Agents, funcionando parcialmente. A continuação dessa história é que a gente tentou vários caminhos pra automatizar o bind por fora — Claude Code via MCP, scripts pelo Scripter, o próprio Figma Agents — e nenhum entregou o suficiente pra escala. O Figma Agents chegava em uns 80%, o que ajuda mas não fecha.

O que destravou foi levar o bind pra dentro do plugin que a gente já tinha construído internamente, em vez de deixar como prompt solto. Ali deu pra colocar regras que o prompt tinha dificuldade de garantir: fallback pro valor mais próximo quando o valor exato não existe — um raio de borda em 9 vira 8, e não vira invenção — e, pra cor, comparação por distância no espaço RGB pra achar a variável semântica correta.

O resultado concreto do lado de design é o que mais me deixa tranquilo do Marco 1: com esse plugin, a gente conseguiu fazer o bind de quase 100% dos componentes que estavam no arquivo de Design System do Figma com os tokens corretos. Não é a arquitetura definitiva de bind do universo. É a que funciona pro nosso arquivo, com o nosso time, agora.

Onde o JSON mora, e por que isso virou discussão

A última surpresa foi de infraestrutura, e é a que mais conversa com o que escrevi em "Antes de AI-first, human-first".

Quando exportamos o JSON dos tokens, ele chegou perto de 40 mil tokens de tamanho — grande demais pra uma LLM ler direto. O Rodolfo colocou um script pra reduzir isso, e o Gabriel propôs minificar o arquivo, tirando os espaçamentos: pra a máquina parsear tanto faz, o problema de legibilidade é só nosso.

E teve um debate de onde esse JSON deveria morar. A opção fácil era deixar tudo no Prolog Cloud, o repositório que centraliza o contexto do produto, porque qualquer PD conseguiria rodar a skill e comitar sem entender de infra. O problema é que jogar um monte de arquivo de token ali pode atrapalhar a indexação da LLM, que já tem bastante coisa pra dar conta.

O caminho que fechamos foi manter o Prolog Cloud como fonte da verdade dos tokens e, a partir de um commit lá, espelhar o arquivo pra um repositório separado de infraestrutura do Design System, que então cascateia as atualizações pro React, pro Flutter e pro Glorp. A gente aceitou aumentar a complexidade da pipeline pra baixar a complexidade de uso. O Glauber, ou qualquer designer, roda a skill e comita — não precisa clonar a infra nem entender como ela funciona. É o mesmo tipo de troca que a gente já tinha feito com a governança: a solução ideal no papel perde pra solução que o time consegue operar sem se afogar.

O que a gente testou, e o que apareceu

Com a fundação de pé, testamos a aplicação de harness nos tokens. A ideia foi pedir pro Claude mostrar visualmente como ele entendeu cada token a partir da documentação, e pedir pra ele montar interfaces de teste — um componente de alerta, por exemplo — só pra ver como ele aplicava os tokens na prática.

Os resultados foram positivos. Ficou razoavelmente claro que o Claude estava entendendo a intenção de cada token — quando usar, quando não usar, o que combina com o quê. Não vou inflar isso além do que foi. Foi um teste inicial, num recorte pequeno, e o objetivo era só ter um sinal de que o schema que a gente escreveu produz o entendimento certo do outro lado. Produziu.

A forma de testar foi simples, peguei toda a documentação de harness para os tokens e pedi pro Claude dizer o que entendeu, rsrsrs, um pouco mais complexo que isso, mas essa foi a ideia, o que gerei foi um relatório com o resultado.

A seguir um resumo do relatório, e um detalhe, Glorp é o nome do Design System da Prolog.

O escopo honesto disso tudo

Aqui vale ser direto sobre o que o Marco 1 entrega e o que ele ainda não entrega.

O que ele entrega é uma fundação de tokens escalável e semi-automatizada, com governança tanto no Figma quanto no código, tokens consumíveis por uma LLM, e quase todos os componentes do arquivo de design amarrados aos tokens certos. É base sólida.

O que ele ainda não entrega é o resultado que dá nome ao projeto: uma LLM montando telas com direção. Esse retorno não vem do harness de token. Como já tinha ficado claro antes, harness de token é diferente de harness de componente, e a maior parte das decisões de interface vai vir dos componentes, não dos tokens soltos. O token pesa quando o Claude precisa criar algo do zero, sem um componente pronto pra reaproveitar. O ganho real de produção mora no harness de componente, que é etapa posterior. Esta primeira parte é a que torna aquela parte possível — não a que colhe o fruto dela.

O que vem

Fechamos o Marco 1 e o Marco 2, que era o harness dos tokens em si, para Prolog Cloud, React e Flutter. O Marco 3, aplicação dos tokens nos componentes, já está em andamento.

Não sei dizer os resultados. Tem a migração dos tokens nos componentes de React e Flutter, que a gente vai atacar com um de-para assistido por IA. Tem uma ideia de criar harness também dos tokens antigos, pra dar ao Claude uma referência de comparação e aumentar a acurácia dessa migração. Tem a dúvida aberta de se aquele JSON minificado vai ser bem consumido em escala. E tem o rollout em produção, com os tokens novos e antigos coexistindo por um tempo. Cada uma dessas frentes pode dar certo, dar errado, ou revelar um problema que eu ainda não enxerguei. É a parte do projeto que eu menos consigo prever, e provavelmente a mais interessante de documentar quando acontecer.