Ninguém gosta de documentar componente. Então eu automatizei. Nobody likes documenting components. So I automated it.

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 gargalo nunca foi o padrão em si. Era o custo de segui-lo.

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 frames, transcrever variantes na mão e escrever definição, contexto 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 atributos ARIA, navegação de foco, área mínima de toque e como comunicar isDisabled pro leitor de tela é outro repertório. 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.

Tratei isso como problema de disciplina por um tempo: cobrava mais, colocava na Definition of Done. Não resolveu. O time não tinha problema de entendimento, tinha problema de fricção.

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

Maurício, coordenador de UX, abriu espaço pra eu construir isso fora da fila de entregas da sprint, 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.

Mapeei 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 e onde ficava a fronteira entre MVP e backlog.

Desse discovery saiu a decisão mais importante do projeto: a v1 não faria nenhuma chamada de API. O plugin seria um intermediário simples, lendo o componente, montando um prompt .md que o designer colava no Gemini corporativo e importava de volta pro plugin renderizar os frames.

Parecia menos ambicioso, e era esse o ponto: eliminava de uma vez os dois maiores riscos de morte prematura do projeto, autenticação corporativa e custo de API, e ainda automatizava a parte que doía, a formatação, 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 com stack, estrutura de arquivos e 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 e segui.

A v1.0 funcionava, mas não bastava para alguém adotar sem eu do lado. As versões seguintes foram sobre fechar essa distância.

Leitura automática de propriedades. O plugin passou a navegar do node até o ComponentSet pai e ler as componentPropertyDefinitions, classificando por convenção (is* vira booleano, state e status viram variante): nove propriedades detectadas sozinhas, sem transcrição manual.

Extração de tokens reais. O maior salto de qualidade do projeto. Antes, a IA inventava nomes de token que não existiam no DS.Sensei, erro que passa despercebido numa revisão rápida por soar plausível. Passei a extrair os tokens reais do componente (cor, tipografia, espaçamento) e injetar no prompt: a alucinação acabou porque a IA parou de precisar adivinhar.

Playground automático. O plugin calcula o produto cartesiano de variantes e monta a grade visual com setProperties(), travada em 200 instâncias pra não derrubar o Figma.

Perguntas contextuais. Quatro perguntas geradas pela IA sobre o componente específico, sempre incluindo uma sobre comportamento no PrimeNinja, nosso programa de assinatura: o designer não escreve a doc, responde o que só ele sabe responder.

Autenticação corporativa. A versão em produção usa Service Account no Vertex AI da empresa, não a chave pessoal de cada designer, e passou por auditoria de segurança interna antes de chegar ao time.

Depois da v1.8 comecei uma v2 bem mais ambiciosa: um fluxo capaz de comparar a documentação anterior com o estado atual do componente, detectar mudanças, calcular a versão SemVer e gerar o changelog a partir do diff.

Tecnicamente funcionava. Na prática, o rollout não se sustentou, e preferi manter a v1.8 estável em produção a empurrar uma versão que ia gerar suporte e desconfiança numa ferramenta que o time tinha acabado de adotar. A v2 segue em beta no meu ambiente, evoluindo devagar.

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 por componente, o equivalente a mais de um dia útil a cada três documentados.

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.

A documentação também virou insumo de handoff: antes, a passagem pro time de dev dependia de conversa (abrir o Figma, medir espaçamento no olho, perguntar qual era o token da cor), e foco e leitor de tela quase nunca chegavam escritos. Agora o card chega no refinamento com estados, tokens, restrições e acessibilidade documentados, e a revisão virou discussão de conteúdo, não mais checklist.

O trabalho que sobra pro 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, 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.

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ó promessa. O template existia há muito tempo: faltava baixo custo de execução, não clareza. Toda vez que um processo não pega no time, vale checar se é entendimento ou fricção, porque a solução muda completamente entre os dois.

IA aplicada rende mais com contexto real do que com prompt refinado. Reescrever o prompt pela décima vez não resolveu a alucinação de token; entregar os tokens reais do componente resolveu de primeira. 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 pronta: adoção interna é frágil, e um problema logo depois de virar padrão derruba a confiança no resto.

Especificar bem importa mais que programar bem. A qualidade do resultado saiu da especificação, não do código, e os bugs mais chatos só apareceram testando em componente real.

Company KaBuM!, Grupo Magalu Product DS.Sensei, the main e-commerce Design System My role Product Designer and maintainer of DS.Sensei Scope Discovery, solution architecture, technical spec, testing, internal rollout, and adoption support Team KaBuM!'s UX team, under Maurício's coordination Tools Figma Plugin API, TypeScript, esbuild, Gemini via Vertex AI, Claude Code Status v1.8 in internal production, used across all business units.

• 73% less time per component documented, down from 4.5h to 1.2h;
• 11 of 11 sections filled in, accessibility included, across every business unit;
• 9 properties read automatically from the component, no manual transcription;
• 1 day between the written spec and a working MVP.

At KaBuM! I maintain DS.Sensei, the Design System for the main e-commerce platform. It was born with me and grew the way design systems grow at a large company: fast on component creation, slow on documentation. The library had a component for almost everything. Documentation, not so much.

And it wasn't for lack of a standard. The standard existed and was formalized: two template frames in Figma (documentComponent and documentPage), versioning tied to the Jira ticket, eleven fixed sections, an accumulating changelog. It was all there, waiting for someone to apply it.

The bottleneck was never the standard. It was the cost of following it.

Three things were blocking the process, and all three surfaced when I talked to the designers across business units.

Documentation was expensive in time: about 4.5 hours per component between setting up the frames, transcribing variants by hand, and writing the definition, usage context, constraints, acceptance criteria, and accessibility. Nobody has 4.5 spare hours mid-sprint, so documentation became the kind of debt everyone acknowledges and nobody pays down.

Accessibility was the weakest point. Designers know how to design the component. Writing ARIA attributes, focus navigation, minimum touch target size, and how to communicate isDisabled to a screen reader is a different skill set. Each business unit wrote accessibility its own way, when it wrote it at all.

There was no completeness validation. Docs would arrive for review missing sections, and review turned into a checklist audit instead of a content discussion. That bottleneck was me, since I was the one reviewing.

I treated this as a discipline problem for a while: pushed harder, added it to the Definition of Done. Didn't work. The team's problem wasn't understanding, it was friction.

The plugin is mine end to end: discovery, architecture, spec, testing, and rollout. But an internal tool doesn't exist in a vacuum, so it's worth separating what was mine from what wasn't.

Maurício, our UX coordinator, made room for me to build this outside the sprint delivery queue, the only reason this project made it out of my personal Figma file.

The designers across business units were a discovery source early on and a testing source through every version. Most of the decisions separating v1.0 from v1.8 came from someone using the plugin on a real component and sending me a screenshot of what broke.

The code implementation was done with Claude Code, working from the spec I wrote. I'm stating that explicitly because it's the point of the project, not a caveat: the team was never blocked by a lack of developers. It was blocked by a lack of someone translating a design problem into an executable requirement.

I mapped the actual process across four blocks of questions: how documentation was done today, what the biggest pain point was (time, inconsistency, or changelog), what the plugin should read from the component, and where the line sat between MVP and backlog.

That discovery produced the project's most important decision: v1 wouldn't make a single API call. The plugin would read the component, assemble a structured .md prompt the designer pasted into the corporate Gemini, then import it back to render the formatted frames.

It looked less ambitious, and that was exactly the point: it eliminated, in one move, the two biggest risks of the project dying early, corporate authentication and API cost, and still automated the part that actually hurt, formatting, not the writing.

Before implementing anything, I wrote two documents: a product spec with flow, fields, and schema, and a CLAUDE.md with the stack, file structure, and implementation order.

With the spec ready, the MVP shipped in a single day, compiling without a single TypeScript error. The first bug showed up within minutes: Figma's plugin runtime doesn't support ?? or ?.. I set the target to ES2015 and moved on.

v1.0 worked, but it wasn't good enough for someone to adopt without me standing next to them. The following versions were about closing that gap.

Automatic property reading. The plugin started navigating from the selected node up to the parent ComponentSet and reading the componentPropertyDefinitions, classifying them by naming convention (is* becomes a boolean state, state and status become variant states): nine properties detected on their own, no manual transcription.

Real token extraction. The biggest quality jump of the project. Before, the AI invented token names that didn't exist in DS.Sensei, an error that slips past a quick review since it reads as plausible. I started extracting the component's actual tokens (color, typography, spacing) and injecting them into the prompt: hallucination stopped because the AI no longer had to guess.

Automatic playground. The plugin calculates the cartesian product of variants and builds the visual grid with setProperties(), capped at 200 instances so an overly complex component doesn't freeze Figma.

Contextual questions. Four AI-generated questions about that specific component, always including one about behavior under PrimeNinja, our subscription program: the designer doesn't write the doc, they answer what only they can answer.

Corporate authentication. The production version uses a company Service Account on Vertex AI, not each designer's own key, and went through an internal security audit before reaching the team.

After v1.8 I started a much more ambitious v2: a flow able to compare the previous documentation against the component's current state, detect changes, and generate the changelog from the diff.

Technically, it worked. In practice, the rollout didn't hold up, and I chose to keep v1.8 stable in production over pushing a version that would generate support tickets and distrust in a tool the team had just adopted. v2 is still in beta in my own environment, evolving slowly.

v1.8 is published internally in KaBuM!'s Figma organization and is the standard way to document a DS.Sensei component today.

73% less time per component documented, down from 4.5 hours to 1.2 hours: that's 3.3 hours given back per component, the equivalent of a full workday for every three documented.

All eleven sections now come in complete, accessibility included, across every business unit. Before, each squad wrote it their own way, or didn't write it at all.

Documentation also became a handoff input: before, handing off to dev depended on conversation (open Figma, eyeball the spacing, ask what token that color was), and focus and screen reader support almost never arrived written down. Now the card reaches refinement with states, tokens, constraints, and accessibility already documented, and review turned into a content discussion, not a checklist.

What's left for the designer to do is exactly what only they can do: answer the context questions and validate the output. The plugin says this outright on its own review screen, because AI generating technical documentation without human validation is just a faster way to spread errors.

DS.Sensei always had a scale problem that no alignment meeting could fix: one maintainer, multiple business units producing components. A tool solved what process couldn't.

There's a straight line connecting this project to the rest of my work at KaBuM!. At KaBuM!GG I learned that a design system dies without governance. At DS.Sensei I learned that governance dies without tooling. The Doc Generator is the third clause in that same sentence.

A standard without a tool is just a promise. The template had existed for a long time: what was missing wasn't clarity, it was a low cost of execution. Whenever a process doesn't stick with a team, it's worth checking whether it's understanding or friction, because the fix is completely different for each.

Applied AI gets more out of real context than a better prompt. Rewriting the prompt for the tenth time didn't fix token hallucination; feeding it the component's actual tokens fixed it on the first try. Prompt engineering takes care of form, context takes care of substance.

Stability beats features in an internal tool. Holding back v2 and keeping v1.8 running was the right call, even with v2 ready: internal adoption is fragile, and a problem right after becoming the standard drags down trust in the rest too.

Writing good specs matters more than writing good code. The quality of the outcome came from the spec, not the code, and the most annoying bugs only showed up testing against a real component.