--- title: Como documentar o design system de um site existente (sem começar do zero) date: 2026-05-12T17:22:55Z modified: 2026-07-29T01:42:02Z permalink: "https://camaraux.com.br/documentar-design-system-site-existente/" type: post status: publish excerpt: Projeto legado sem DS documentado? Veja como extrair tokens, auditar a interface e gerar o design.md em minutos. wpid: 7656 categories: - Design Systems tags: - Design Systems - auditoria visual - Design System - Design Tokens - design.md - Documentação de Design - inventário de interface - produto legado - site to design.md rank_math_title: "Documentar design system de site existente: guia prático" rank_math_description: "Saiba como documentar o design system de um site existente: auditoria visual, extração de tokens e geração do design.md passo a passo.\\n" rank_math_focus_keyword: documentar design system,site existente featured_image: /wp-content/uploads/2026/05/Documentar-design-system-de-site-existente.webp featured_image_alt: Ilustração minimalista de documentar design system site existente em tons de roxo author: Lucas Camara timestamp: 2026-07-29T01:42:02Z --- Você entrou num projeto novo, o produto já está no ar há anos e ninguém sabe dizer onde ficam as cores oficiais, qual é a fonte do título ou por que existem três variações de botão primário espalhadas pelo sistema. Não tem Figma atualizado, não tem guia de estilo e os desenvolvedores trabalham na base do “copia daquela tela ali”. Esse é o cenário mais comum em produtos digitais maduros. Mais de 70% das equipes de design trabalham com sistemas legados que nunca tiveram um design system documentado formalmente. O problema não é a falta de padrões: o produto sobreviveu até aqui, então alguma consistência existe. O desafio é tornar essa consistência visível, nomeada e reutilizável. Documentar o design system de um site existente significa exatamente isso: extrair o que já existe no produto, organizar como linguagem de design e formalizar em um arquivo que o time inteiro consegue consultar e manter. ## O que é documentar o design system de um site existente? Documentar o design system de um site existente é o processo de auditar visualmente um produto digital em produção, extrair seus design tokens (cores, tipografia, espaçamento, bordas, sombras), catalogar os componentes recorrentes e reunir tudo em uma referência estruturada. Diferente de criar um design system do zero, aqui você parte do que o produto já usa, não do que você gostaria que ele usasse. ## Por que projetos legados não têm design system documentado A resposta curta: o produto cresceu rápido demais para que alguém parasse para documentar. A resposta real é mais complexa. Produtos lançados antes de 2018 raramente nasceram com a cultura de design system. Cada entrega resolvia o problema imediato, cada designer novo trazia sua própria interpretação dos padrões visuais e o CSS foi crescendo com variáveis repetidas, valores fixos no código e decisões tomadas em contexto que ninguém mais lembra. Quando uma nova squad chega ou quando o produto começa a escalar para múltiplas plataformas, a inconsistência vira custo. Retrabalho de desenvolvimento, inconsistência visual entre módulos e um handoff que depende de memória coletiva em vez de documentação real. Documentar o que existe não é trabalho de arquivo. É o primeiro passo para transformar um produto que sobreviveu em um produto que escala. ## Como fazer a auditoria visual antes de documentar Nenhuma documentação começa pelo Figma. Começa pela observação sistemática do produto real. A auditoria visual é o processo de catalogar o que o produto realmente usa, não o que a última especificação dizia que deveria usar. ### O que é um inventário de interface? Um inventário de interface é um mapeamento visual de todos os elementos recorrentes de um produto: cada botão, cada campo de formulário, cada tipografia, cada variação de card. O objetivo não é julgar o que está certo ou errado, mas registrar o que existe. Com esse inventário em mãos, você consegue identificar quais são os padrões reais, quais são as exceções e onde estão as inconsistências que precisam ser resolvidas antes de documentar. ### Quais elementos mapear na auditoria visual? Uma auditoria visual completa cobre no mínimo seis categorias: paleta de cores em uso (primárias, secundárias, feedbacks, neutros), escala tipográfica (famílias, pesos, tamanhos por hierarquia), sistema de espaçamento (margens internas, gaps, paddings recorrentes), componentes de interface (botões, inputs, cards, navegação, modais), estados de componente (padrão, hover, foco, erro, desativado) e padrões de layout (grid, colunas, breakpoints). Cobrir essas seis categorias garante que a documentação final seja suficiente para guiar tanto designers quanto desenvolvedores. ## Como extrair design tokens de um site existente Design tokens são os valores nomeados que compõem a linguagem visual do sistema. Extraí-los de um site em produção é, na prática, ler o CSS real do produto e transformar valores avulsos em variáveis com nome e significado. A ideia central da [metodologia Atomic Design](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/metodologia-atomic-design.md) é exatamente essa: tokens são os elementos mais básicos do sistema, a camada que fica abaixo dos átomos e define as regras visuais que se propagam por toda a interface. Antes de documentar qualquer componente, os tokens precisam estar mapeados. ## Como identificar tokens de cor a partir do CSS? Abra o DevTools do navegador em qualquer página do produto, vá até a aba “Sources” ou “Elements” e inspecione os valores hexadecimais aplicados nos elementos principais. Anote cada cor única que aparecer. Depois, classifique: quais são as cores de marca, quais são os feedbacks (erro, sucesso, alerta, informação) e quais são os neutros (cinzas de texto, bordas, fundos). Esse agrupamento já é a estrutura do seu token de cor. ### Como documentar tipografia e espaçamento? Para tipografia, registre as famílias utilizadas, todos os tamanhos em pixels ou rem, pesos (regular, medium, semibold, bold) e a altura de linha de cada variação. Para espaçamento, inspecione os paddings e margins mais recorrentes, identifique o padrão base (geralmente 4px ou 8px) e construa a escala a partir daí. Produtos consistentes geralmente usam múltiplos de 4 ou 8 sem que ninguém tenha formalizado isso. ## Como gerar o arquivo design.md com a extensão Site to DESIGN.md Fazer essa extração manualmente funciona, mas é lento e sujeito a erros. Para agilizar o processo, desenvolvi a extensão **Site to DESIGN.md**, disponível gratuitamente no Chrome e listada entre as [extensões para designers mais úteis no dia a dia](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/extensoes-chrome-para-designers.md). A extensão lê o CSS computado do site em produção, extrai automaticamente os valores de cor, tipografia e espaçamento e gera um arquivo `design.md` estruturado, pronto para servir como ponto de partida para a documentação do design system. ### O que a extensão Site to DESIGN.md faz? A extensão varre o DOM e os estilos computados da página ativa, agrupa os valores encontrados por categoria de token e exporta um arquivo Markdown com a estrutura básica do design system: paleta de cores com hexadecimais, escala tipográfica com família e tamanhos, valores de espaçamento recorrentes e lista de componentes identificados. O resultado não substitui o trabalho de curadoria, mas elimina a fase mais trabalhosa da auditoria. ### Como usar a extensão passo a passo? Instale a extensão pelo Chrome Web Store. Com ela instalada, abra o site que você quer auditar. Clique no ícone da extensão na barra do navegador. Selecione as categorias que quer extrair (cores, tipografia, espaçamento ou todos). Clique em “Gerar design.md”. O arquivo será baixado automaticamente na sua pasta de downloads. Abra o arquivo num editor de texto ou importe diretamente para o Notion, Confluence ou como referência no seu arquivo Figma. O processo completo leva menos de dois minutos para qualquer site, independente da complexidade. ## Como organizar a documentação gerada no Figma Com o arquivo `design.md` em mãos, o próximo passo é transformar os valores extraídos em estilos e variáveis dentro do Figma. O guia completo sobre [como estruturar design systems no Figma](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-systems-figma.md) cobre esse processo em detalhe, mas os passos essenciais são três. Primeiro, crie uma página de tokens no arquivo Figma e registre cada valor como estilo de cor, estilo de texto ou variável local. Segundo, revise os tokens extraídos: elimine duplicatas, decida quais variações são padrão e quais são exceções, e nomeie tudo com convenção semântica ($color-brand-primary, $spacing-md, $text-heading-lg). Terceiro, construa os componentes base referenciando os tokens, não valores fixos. Isso garante que qualquer mudança futura num token se propague para todo o sistema de uma vez. Para times que precisam de um handoff completo entre design e desenvolvimento, a [documentação de design para desenvolvedores](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/documentacao-de-design-handoff-para-desenvolvedores.md) detalha como estruturar as especificações de componente de forma que o time de engenharia consiga implementar sem depender de explicações verbais. ## Conclusão Documentar o design system de um site existente não começa com uma decisão estratégica de produto. Começa com uma tela aberta, o DevTools no lado e a disposição de registrar o que já existe antes de tentar mudar qualquer coisa. A auditoria visual revela os padrões reais. A extração de tokens nomeia esses padrões. A organização no Figma os torna reutilizáveis. E a extensão Site to DESIGN.md acelera a parte mais trabalhosa do processo, gerando a estrutura inicial em minutos. Se você está entrando em um projeto legado ou precisa estruturar o design system de um produto que nunca teve documentação formal, o ponto de partida é mais simples do que parece. **Lucas Câmara** é Product Designer Sênior com experiência em produtos financeiros digitais de alta escala. Fundador da CamaraUX, consultoria especializada em UX para produtos digitais. [Ver currículo completo](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/page/curriculo.md) Precisa de uma auditoria de UI completa para o seu produto? [Fale com a CamaraUX](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/page/contato.md) e veja como transformar um sistema legado em um design system funcional. ## Topics **Categorias:** [Design Systems](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/category/design-systems.md) **Tags:** [auditoria visual](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/auditoria-visual.md), [Design System](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-system.md), [Design Tokens](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-tokens.md), [design.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-md.md), [Documentação de Design](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/documentacao-de-design.md), [inventário de interface](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/inventario-de-interface.md), [produto legado](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/produto-legado.md), [site to design.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/site-to-design-md.md)