Antes de AI-first, human-first

Leia no Medium (Português) | Read on Medium (English)

No artigo anterior contei como estamos construindo o Projeto Harness Design System. O plano era claro: começar com poucos componentes, testar com Claude Code, aprender antes de escalar.

A pergunta natural depois daquele texto seria começar por quais componentes. Essa foi a pergunta que eu trouxe pra essa semana. E quando fui responder, descobri que existia uma pergunta anterior a ela. Antes de decidir qual componente vem primeiro, eu precisei decidir o que vem antes dos componentes. É sobre isso esse artigo.

A ordem que ficou clara essa semana

A regra que eu cheguei é simples de enunciar e mais difícil de seguir: antes de AI-first, human-first.

Aplicar uma camada de IA em cima de um fluxo que ainda tem fricção entre designer e desenvolvedor não resolve a fricção. Multiplica ela. Se o design system não está sincronizado entre Figma e código hoje, no fluxo tradicional, qualquer agente que tente consumir esse sistema vai trabalhar com duas fontes de verdade ao mesmo tempo. O problema que já existe vai ficar mais opaco, não mais visível.

Mesmo no cenário em que a IA produzir cada vez mais, vai sempre ter humano operando em algum momento. Designer revisando. Desenvolvedor refatorando. Stakeholder validando. Se esse humano não consegue confiar na fundação, ele vai corrigir coisa que a IA gerou e o resultado vai parecer aleatório. A ordem é arrumar a base, depois construir em cima.

Onde a base está hoje

Nas duas últimas semanas, eu e o Glauber Franco terminamos a tokenização completa no Figma. Aplicamos os tokens em componentes que já existiam, começando pelos mais simples como botões e inputs. Durante essa aplicação fomos descobrindo lacunas semânticas. Cor de borda que não tinha token. Background que precisava de uma variante nova. Sombras que não estavam mapeadas. Cada lacuna virou um ajuste na variável correspondente.

Um efeito colateral interessante apareceu nesse processo: o dark mode quase de brinde. Quando você trabalha com tokens e variables direito, o dark mode deixa de ser projeto futuro e vira algo possível de ativar. Não era prioridade no escopo, mas chegamos a um ponto onde testar dark mode foi quase trivial. As pessoas do time ficaram animadas, stakeholders também. Esse tipo de retorno inesperado é o que acontece quando o trabalho de fundação é feito direito. Você arruma a base e ganha coisas que não tinha pedido.

O problema que ainda falta resolver

Os tokens estão prontos no Figma. No código, não.

Se eu publicasse o design system agora, com os tokens novos no Figma e os antigos rodando em produção, criaria um problema pior que o atual. Designers começariam a entregar handoffs com cores e tipografias que o desenvolvedor não tem como aplicar. Cada tela usada em discussão com stakeholder pareceria uma decisão tomada, mas o que sairia em produção seria diferente. O ruído entre o Figma e o código vai aparecer em todas as conversas, e ninguém ganha tempo com isso.

Esse é o tipo de problema que parece pequeno no slide e se torna grande quando atinge um sprint inteiro. Vou tomar cuidado pra evitá-lo.

O que vem na próxima semana

A próxima semana é dedicada a alinhar com os desenvolvedores React e Flutter como eles vão aplicar a tokenização no código que já está em produção. Esse trabalho não é pequeno. Cada cor hardcoded, cada referência direta a um valor que deveria ser token, precisa ser revisada. É trabalho de garimpagem. Só depois disso o design system pode ser publicado no Figma e o fluxo human-first volta a estar coerente.

Em paralelo, começamos a investigar uma pergunta que eu ainda não sei responder: como tornar os tokens consumíveis por uma LLM. Aqui vale uma distinção que tem virado importante no Projeto Harness Design System. Harness Design é a disciplina mais ampla, o desenho de todo o sistema pra que a IA consiga produzir com direção. LLM-readiness é uma prática específica dentro disso: documentar e estruturar artefatos pra que uma LLM consiga lê-los e usá-los corretamente. Tornar componentes LLM-ready é parte do Harness Design. Tornar tokens LLM-ready também, e ainda não está claro quanto trabalho isso vai exigir. Pode ser pequeno, pode ser grande. Vou descobrir na semana que vem.

Depois disso, os componentes. E aí volta a pergunta inicial

Quando essa primeira camada estiver fechada, a pergunta de começar por quais componentes volta com peso. E a resposta intuitiva de pegar os mais usados não basta sozinha. Aplicar LLM-readiness em componentes sem ter um jeito de testar se a aplicação está funcionando vira atividade sem feedback. Você melhora documentação, segue pro próximo componente, e nunca sabe se o que fez produziu resultado. Pra testar, você precisa de um cenário concreto.

A decisão: ancorar num padrão de tela

Olhei pro nosso sistema e identifiquei o padrão de tela que mais se repete. Ele tem quatro componentes principais: menu, topbar, header e tabela. É o padrão mais básico que temos, e também o mais frequente. Vou começar por aí. A decisão resolve três coisas ao mesmo tempo.

Primeira: os componentes desse padrão estão entre os mais usados no sistema. Trabalhar eles primeiro tem retorno alto mesmo que o experimento de IA não dê o resultado esperado, porque uma documentação melhor pra eles serve também pro fluxo human-first.

Segunda: se o Claude Code não conseguir reproduzir bem essa tela, que é a mais simples e padronizada que temos, dificilmente vai conseguir reproduzir nada mais complexo. Isso me dá um critério de falha claro, em vez de uma sensação vaga de que está mais ou menos.

Terceira: já temos várias versões dessa tela construídas manualmente, no fluxo tradicional. Isso vira caso de controle. Posso comparar o que o Claude Code gera com o que o time produziu sem IA, e ver se está no mesmo nível, abaixo, ou se precisa de tanto ajuste que não compensa.

O que o experimento vai testar de fato

Depois que os tokens estiverem aplicados no código e esses quatro componentes estiverem com a documentação de LLM-readiness, eu vou pedir pro Claude Code montar uma tela desse padrão. A pergunta é se o resultado tem qualidade próxima da versão manual, sem precisar de muito ajuste.

A resposta vai ser sim, não, ou parcialmente. Qualquer uma das três é informação útil. Sim significa que o caminho funciona e dá pra escalar. Não significa que algo está errado em algum lugar, e parte do trabalho vai ser descobrir se é na documentação, no método, ou em uma premissa que eu não enxerguei ainda. Parcialmente é o cenário mais provável e o mais interessante de documentar, porque vai mostrar onde funciona, onde quebra, e onde precisa refinar.

A ordem do Projeto Harness Design System

Resumindo a ordem que ficou clara essa semana. Tokens no código primeiro. Design system publicado no Figma na sequência. LLM-readiness de tokens investigada em paralelo. Depois disso, componentes do padrão de tela mais repetido, ancorados num experimento com caso de controle.

Cada camada tem que funcionar antes da próxima ser confiável. Esse artigo é sobre como cheguei nessa ordem. Os próximos vão contar o que aconteceu quando saí dela pra prática, com as surpresas que aparecerem no caminho.