Ninguém gosta de documentar componente. Então eu automatizei.

Empresa KaBuM!, Grupo Magalu Produto DS.Sensei, Design System do e-commerce principal Meu papel Product Designer e mantenedor do DS.Sensei Escopo Discovery, arquitetura da solução, especificação técnica, testes, publicação interna e suporte à adoção Time Time de UX do KaBuM!, sob coordenação de Maurício Ferramentas Figma Plugin API, TypeScript, esbuild, Gemini via Vertex AI, Claude Code Status v1.8 em produção interna, usada por todas as torres.

• 73% menos tempo por componente documentado, de 4,5h para 1,2h;
• 11 de 11 seções preenchidas, incluindo acessibilidade, em todas as torres;
• 9 propriedades lidas automaticamente do componente, sem transcrição manual;
• 1 dia entre a especificação escrita e o MVP funcionando.

No KaBuM! eu mantenho o DS.Sensei, o Design System do e-commerce principal. Ele nasceu comigo e cresceu do jeito que design system cresce em empresa grande: rápido na criação de componente, devagar na documentação. A biblioteca tinha componente para quase tudo. A documentação, não.

E não era por falta de padrão. O padrão existia e estava formalizado: dois frames template no Figma (documentComponent e documentPage), versionamento amarrado ao código do Jira, onze seções fixas, changelog acumulado. Estava tudo lá, esperando alguém aplicar.

O problema nunca foi o padrão. Foi o custo de aplicar o padrão.

Três coisas travavam o processo, e as três apareceram quando fui conversar com os designers das torres.

Documentar custava caro em tempo. Cerca de 4,5 horas por componente entre montar os frames, transcrever variantes e estados na mão, escrever definição, contextos de uso, restrições, critérios de aceite e acessibilidade. Ninguém tem 4,5 horas sobrando no meio de uma sprint, então a documentação virava aquela dívida que todo mundo reconhece e ninguém paga.

Acessibilidade era o ponto mais fraco. Designer sabe desenhar o componente. Escrever quais atributos ARIA ele precisa, como o foco navega, qual o tamanho mínimo de área de toque, como comunicar isDisabled para leitor de tela: isso já é outro repertório. O resultado é que cada torre escrevia acessibilidade do seu jeito. Quando escrevia.

Não existia validação de completude. A doc chegava para revisão faltando seção, e a revisão virava conferência de checklist em vez de discussão de conteúdo. Gargalo em mim, que era quem revisava.

Passei um tempo tratando isso como problema de disciplina, cobrando mais e colocando na Definition of Done. Não resolveu, porque o time não estava com problema de entendimento. Estava com problema de fricção.

O plugin é meu de ponta a ponta em discovery, arquitetura, especificação, teste e publicação. Mas ferramenta interna não existe sozinha, então vale separar o que foi meu do que não foi.

Maurício, coordenador de UX, abriu espaço para eu construir isso fora da fila de entregas da sprint, o que é a única razão pela qual o projeto saiu do meu Figma pessoal.

Os designers das torres foram fonte de discovery no começo e de teste durante todas as versões. Boa parte das decisões que separam a v1.0 da v1.8 veio de alguém usando o plugin em componente real e me mandando print do que quebrou.

A implementação do código foi feita com Claude Code a partir da especificação que eu escrevi. Deixo isso explícito porque é o ponto do projeto, não uma ressalva: o time nunca esteve travado por falta de desenvolvedor, e sim por falta de alguém traduzindo um problema de design em requisito executável.

Comecei mapeando o processo real em quatro blocos de perguntas: como a documentação era feita hoje, qual era a maior dor (tempo, inconsistência ou changelog), o que o plugin deveria ler do componente selecionado e onde ficava a fronteira entre MVP e backlog.

Desse discovery saiu a decisão arquitetural mais importante do projeto: a v1 não faria chamada de API nenhuma. O plugin seria um intermediário deliberadamente simples. Ele leria o componente, montaria um prompt .md estruturado, o designer colaria esse prompt no Gemini corporativo e depois importaria o .md de volta para o plugin renderizar os frames formatados.

Parecia menos ambicioso, e era exatamente esse o ponto. Essa decisão eliminou de uma vez os dois maiores riscos de morte prematura do projeto, que eram autenticação corporativa e custo de API. E ainda automatizava a parte que realmente doía: a formatação e a estrutura, não a escrita.

Antes de implementar qualquer coisa, escrevi dois documentos: uma especificação de produto com fluxo, campos e schema, e um CLAUDE.md na raiz do repositório com stack, estrutura de arquivos, manifest, tipos TypeScript, estilos de texto e a ordem de implementação.

Com a especificação pronta, o MVP saiu em um único dia, compilando sem erro de TypeScript. O primeiro bug apareceu em minutos: o runtime de plugins do Figma não suporta ?? nem ?.. Ajustei o target para ES2015 no tsconfig e no esbuild e segui.

A v1.0 funcionava. Ela só não era boa o suficiente para alguém adotar sem eu estar do lado, que é uma distância maior do que parece. As versões seguintes foram sobre fechar essa distância.

Leitura automática de propriedades. O plugin passou a navegar do node selecionado até o ComponentSet pai e ler as componentPropertyDefinitions, classificando por convenção de nomenclatura (is* vira estado booleano, state e status viram estado de variante). Nove propriedades detectadas sozinho é meia hora de transcrição manual que deixou de existir.

Extração de tokens reais. Esse foi o maior salto de qualidade. Antes, a IA inventava nomes de token que não existiam no DS.Sensei, e esse é o pior tipo de erro porque o texto fica plausível e passa despercebido na revisão rápida. Passei a extrair os tokens reais do componente (cores via boundVariables, tipografia via TextNodes, espaçamentos via padding, gap e corner radius) e injetá-los no prompt. A alucinação de token acabou porque a IA parou de precisar adivinhar.

Playground automático. O plugin calcula o produto cartesiano de variantes e cria as instâncias com setProperties(), montando a grade visual com label por linha e por coluna. Com trava de 200 instâncias, porque componente muito complexo trava o Figma.

Perguntas contextuais. Quatro perguntas geradas pela IA sobre aquele componente específico, incluindo uma sempre sobre comportamento no PrimeNinja, nosso programa de assinatura. Isso resolveu o problema da documentação genérica: o designer não escreve a doc, ele responde quatro perguntas que só ele sabe responder.

Autenticação corporativa. A versão em produção usa Service Account no Vertex AI da empresa, em vez de cada designer usar a própria chave. Passou por auditoria de segurança interna antes de ir para o time.

Depois da v1.8 comecei uma v2 com uma funcionalidade bem mais ambiciosa: um fluxo de evolução capaz de comparar a documentação anterior com o estado atual do componente no Figma, detectar mudanças estruturais e visuais, calcular a próxima versão SemVer sozinho e gerar o changelog descritivo a partir do diff.

Tecnicamente funcionava. Na prática, o rollout para o time não se sustentou, e eu preferi manter a v1.8 estável rodando em produção a empurrar uma versão que ia gerar suporte e desconfiança em cima de uma ferramenta que o time tinha acabado de adotar.

A v2 continua em beta, no meu ambiente, evoluindo devagar. Ferramenta interna vive de confiança, e confiança é bem mais cara de reconquistar do que de manter.

A v1.8 está publicada internamente na organização KaBuM! do Figma e é a forma padrão de documentar componente do DS.Sensei hoje.

73% de redução de tempo por componente documentado, de 4,5 horas para 1,2 hora. São 3,3 horas devolvidas a cada componente: a cada três componentes documentados, mais de um dia útil inteiro volta para o time.

As onze seções passaram a vir completas, acessibilidade inclusa, em todas as torres. Antes cada squad escrevia do seu jeito, ou não escrevia. Esse era o resultado que eu mais queria e o que eu menos acreditava que fosse acontecer por cobrança.

A documentação virou insumo de handoff. Antes, a passagem para o time de desenvolvimento dependia de conversa: o dev abria o Figma, media espaçamento no olho, perguntava no chat qual era o token daquela cor, e comportamento de foco e leitor de tela quase nunca chegava escrito. Agora o card chega no refinamento com estados, tokens, restrições, critérios de aceite e requisitos de acessibilidade documentados.

O tempo de revisão caiu junto. Como a completude é validada antes do envio, a revisão deixou de ser conferência de checklist e voltou a ser discussão de conteúdo.

O trabalho que sobrou para o designer é o que só ele pode fazer: responder as perguntas de contexto e validar a saída. O plugin avisa isso na própria tela de revisão, com todas as letras, porque IA gerando documentação técnica sem validação humana é só uma forma mais rápida de espalhar erro.

O DS.Sensei sempre teve um problema de escala que nenhuma reunião de alinhamento resolvia: um mantenedor, várias torres produzindo componente. Ferramenta resolveu o que processo não resolvia, porque processo depende de disciplina e disciplina compete com prazo de sprint.

Tem uma linha reta ligando esse projeto ao resto do meu trabalho no KaBuM!. No KaBuM!GG eu aprendi que design system morre sem governança. No DS.Sensei eu aprendi que governança morre sem ferramenta. O Doc Generator é a terceira etapa dessa mesma frase.

Padrão sem ferramenta é só uma promessa. O template de documentação existia há muito tempo e era bom. Não faltava clareza, faltava custo baixo de execução. Toda vez que um processo não pega no time, vale checar se o problema é entendimento ou fricção, porque a solução é completamente diferente nos dois casos.

IA aplicada precisa de contexto real, não de prompt melhor. Reescrever o prompt pela décima vez não resolveu a alucinação de token. Entregar os tokens reais do componente resolveu na primeira tentativa. Prompt engineering cuida da forma, contexto cuida da substância.

Estabilidade vale mais que funcionalidade em ferramenta interna. Segurar a v2 e manter a v1.8 rodando foi a decisão certa, mesmo com a v2 tecnicamente pronta. Adoção interna é frágil: o time testa uma ferramenta nova uma vez, e se ela dá problema logo depois de virar padrão, você não perde só a versão nova, perde a confiança na ferramenta inteira.

Designer não precisa virar dev, precisa ficar bom em especificar. O que determinou a qualidade do resultado foi a especificação, não o código. Os bugs mais chatos do projeto só apareceram testando em componente real, nunca em revisão de código.