Como documentar um componente do design system numa tarde, sem escrever um manual

    19 de novembro de 2026
    11 min de leitura
    Por Orson Vale
    Compartilhar este artigo

    A terceira equipa de produto acabou de abrir um pedido para "um botão com ícone à direita e carregamento". O botão já existe. Faz exatamente isso, com a propriedade iconPosition e o estado loading, mas ninguém o sabe porque a página do componente no portal tem 40 secções, começa com a filosofia da marca e só chega às propriedades depois de quatro ecrãs de rolagem. Entretanto, alguém da equipa de checkout já fez uma cópia local com outro raio de canto.

    Este é o problema real da documentação de componentes: raramente falta texto, falta a resposta certa no sítio onde a pessoa a procura. O caminho rápido passa por escrever menos, numa ordem fixa, e aceitar que a página cresce com as perguntas que as equipas fazem, não com as que o sistema imagina.

    A página mínima que responde a quem vai usar o componente

    Uma página de componente serve dois leitores com pressa. A designer quer saber se o componente resolve o caso dela e que variante escolher. O programador quer saber que propriedades existem, que valores aceitam e o que acontece com o teclado. Tudo o que não ajuda nenhum dos dois pode esperar.

    Para um primeiro componente, seis blocos chegam, por esta ordem:

    1. Uma frase sobre o que o componente faz e uma sobre quando não o usar.
    2. Um exemplo vivo ou uma imagem com as variantes principais lado a lado.
    3. A tabela de anatomia, variantes e estados.
    4. As propriedades da API com tipo, valor por omissão e descrição curta.
    5. Três a cinco regras de uso, cada uma com um exemplo certo e um errado.
    6. As notas de acessibilidade: teclado, leitor de ecrã, contraste e área de toque.

    A frase sobre quando não usar o componente é a que mais trabalho poupa. "Use o Toast para confirmar ações; não o use para erros que exigem ação do utilizador" elimina metade das más utilizações antes de alguém chegar à tabela. Equipas que documentam só o caso positivo descobrem as más utilizações nas revisões de design, três sprints depois.

    Esta ordem não é original. O Material Design 3, o Carbon da IBM e o GOV.UK Design System usam variações dela, e a GOV.UK é particularmente boa a abrir cada componente com "quando usar" e "quando não usar" antes de qualquer detalhe visual. Copiar a estrutura de um sistema público maduro poupa a discussão interna sobre o formato e deixa a equipa focada no conteúdo.

    Numa tarde de quatro horas, um componente simples como um botão ou um campo de texto fica com estes seis blocos preenchidos. Um componente composto, como uma tabela de dados com ordenação e paginação, pede mais tempo, mas a mesma estrutura.

    Anatomia, variantes e estados cabem numa tabela

    A tentação é descrever cada variante num parágrafo. O resultado é um texto que ninguém compara. Uma tabela obriga a responder às mesmas perguntas para todas as variantes e deixa à vista as combinações que não existem ou que ninguém testou.

    Para um botão, a tabela pode ficar assim:

    Variante Uso principal Estados suportados Contraste mínimo Notas
    Primário Uma ação principal por ecrã normal, hover, foco, premido, carregamento, desativado 4,5:1 no texto Nunca dois primários lado a lado
    Secundário Ações alternativas normal, hover, foco, premido, desativado 4,5:1 no texto, 3:1 no contorno Pode coexistir com um primário
    Terciário (texto) Ações de baixa prioridade, "Cancelar" normal, hover, foco, premido 4,5:1 no texto Sem contorno, precisa de indicador de foco visível
    Destrutivo Apagar, remover, revogar normal, hover, foco, premido, carregamento 4,5:1 no texto Pede confirmação se a ação não puder ser anulada

    Os valores de contraste vêm das WCAG 2.2: 4,5:1 para texto normal (critério 1.4.3) e 3:1 para componentes de interface e indicadores gráficos (critério 1.4.11). Pôr o número na tabela evita que alguém troque a cor do contorno do secundário por um cinzento mais elegante que não passa no teste.

    A anatomia vai num diagrama simples com números: 1 contentor, 2 etiqueta, 3 ícone opcional, 4 indicador de carregamento. Cada número corresponde a uma linha que diz se a parte é obrigatória e que token de design controla a sua cor, espaçamento ou tipografia. Quando o programador vê color.action.primary.background ao lado do número 1, já não precisa de abrir o Figma para descobrir o hexadecimal.

    Os estados merecem uma linha à parte para o foco. É o estado que mais vezes desaparece numa reformulação visual, porque ninguém o vê em capturas de ecrã feitas com o rato. Documentar o indicador de foco com espessura e cor, por exemplo 2 px com contraste de 3:1 face ao fundo, transforma uma preferência estética numa regra verificável.

    Figma, Storybook ou portal: onde guardar cada parte

    Não existe um sítio único que sirva todos os leitores. O Figma é onde a designer já está, o Storybook é onde o programador testa, e um portal como o Zeroheight ou o Supernova junta as duas coisas para quem não trabalha em nenhuma delas, como a equipa de conteúdo ou a de QA. A pergunta útil é onde vive a fonte de verdade de cada bloco.

    Estas perguntas, respondidas por ordem, decidem a arquitetura para a maioria das equipas:

    1. O sistema tem menos de 15 componentes e uma só equipa a consumi-lo? Se sim, a descrição do componente no Figma mais as histórias do Storybook chegam. Se não, segue para a pergunta 2.
    2. Há pessoas que precisam da documentação e não abrem nem o Figma nem o repositório, por exemplo gestores de produto, redatores ou parceiros externos? Se sim, segue para a pergunta 3. Se não, o Storybook com Autodocs e páginas MDX pode ser o portal, e a pergunta 4 decide o resto.
    3. A equipa tem orçamento e alguém disponível para manter uma ferramenta paga? Se sim, um portal dedicado que incorpora frames do Figma e histórias do Storybook evita duplicar conteúdo. Se não, um site estático gerado a partir do repositório faz o mesmo papel com mais trabalho inicial.
    4. As propriedades mudam com frequência, por exemplo em cada release quinzenal? Se sim, a tabela de propriedades tem de ser gerada a partir do código, nunca escrita à mão. Se não, uma tabela manual com data de revisão aguenta.

    A regra prática que resulta disto: as regras de uso e os exemplos visuais nascem no design, a tabela de propriedades nasce no código, e o portal apenas mostra as duas. Quando a mesma informação é escrita duas vezes, uma das cópias fica errada no primeiro trimestre.

    O Figma Dev Mode ajudou a reduzir a distância, porque mostra propriedades de componentes e ligações ao código diretamente no ficheiro. Ainda assim, não substitui uma página com regras de uso: o Dev Mode diz o que existe, não diz quando escolher uma variante em vez de outra.

    Regras de uso que evitam os erros mais caros

    As regras de uso são a parte que distingue documentação de inventário. Um inventário lista o que existe. Uma regra diz o que fazer numa situação concreta e, de preferência, mostra um exemplo errado ao lado do certo.

    As melhores regras saem de erros reais. Em vez de escrever regras em abstrato, a equipa do sistema pode rever os últimos 20 pedidos de ajuda ou comentários em revisões de design e procurar padrões. Se cinco desses 20 pedidos envolvem botões primários duplicados, a primeira regra está escrita.

    Alguns formatos que funcionam bem:

    • "Use X quando..., use Y quando...". Força a comparação com o componente vizinho, que é onde as pessoas hesitam.
    • Exemplo certo e errado lado a lado, com uma frase curta a explicar o problema do errado.
    • Limites numéricos: "etiquetas até 3 palavras", "no máximo 5 opções num grupo de rádios antes de passar para uma lista pendente".
    • Regras de texto: verbo no infinitivo nas etiquetas ("Guardar", "Enviar pedido"), sem pontos finais, sem maiúsculas a meio.

    As regras de acessibilidade merecem um bloco próprio porque são as que mais custam quando falham. Para cada componente interativo, a página deve dizer que teclas fazem o quê (Tab, Enter, Espaço, Esc, setas), que papel ARIA o componente expõe e o que o leitor de ecrã anuncia.

    Também a área de toque: as WCAG 2.2 pedem pelo menos 24 por 24 píxeis CSS no critério 2.5.8 (nível AA), e muitas equipas adotam 44 por 44, que é o valor do critério 2.5.5 (nível AAA) e o que as diretrizes da Apple recomendam em pontos.

    Há um argumento contra regras detalhadas que merece resposta: regras a mais tornam o sistema rígido e as equipas começam a contorná-lo. É verdade quando as regras proíbem sem explicar. Uma regra que diz porquê ("dois primários lado a lado confundem qual é a ação principal") deixa margem para a exceção bem justificada. Uma que diz apenas "proibido" gera cópias locais.

    Manter a documentação viva quando o componente muda

    A documentação envelhece mais depressa do que o componente. A versão 1 sai com uma página impecável, a versão 2 acrescenta uma propriedade que só aparece no Storybook, e na versão 3 a imagem principal ainda mostra o raio de canto antigo. Ninguém decidiu deixar a página desatualizada; simplesmente não havia um passo no processo que a obrigasse a mudar.

    Três mecanismos resolvem a maior parte disto:

    1. A página faz parte da definição de pronto do componente. Um pull request que altera propriedades públicas não é aprovado sem a alteração correspondente na documentação, e o revisor verifica as duas coisas.
    2. Um registo de alterações curto no fundo de cada página, com data, versão e uma linha por mudança. Quem chega à página vê de imediato se a versão que está a usar no seu produto é a mesma que está documentada.
    3. Uma revisão trimestral de 30 minutos por componente crítico, em que alguém de fora da equipa do sistema usa a página para construir um caso simples e anota onde se perdeu.

    O registo de alterações tem um benefício lateral: dá às equipas de produto um motivo para atualizar. Uma linha como "versão 2.4: o estado de carregamento passou a bloquear cliques duplicados" vende a atualização melhor do que qualquer anúncio no canal interno.

    Medir também ajuda, desde que a métrica seja simples. O número de perguntas no canal de suporte do design system por componente, contado por mês, mostra que páginas não estão a responder. Se o seletor de datas gera 12 perguntas por mês e o botão gera uma, o tempo de documentação deve ir para o seletor de datas.

    Dúvidas que aparecem quando se documenta o primeiro componente

    Quem deve escrever a documentação de um componente? Quem desenhou o componente escreve o primeiro rascunho das regras de uso, e quem o implementou escreve a tabela de propriedades. Uma terceira pessoa, de outra equipa de produto, lê a página e tenta usar o componente só com ela. As perguntas que essa pessoa fizer são as secções que faltam.

    Vale a pena documentar componentes que só uma equipa usa? Vale uma versão de cinco linhas: para que serve, quem é o dono e onde está o código. Componentes locais promovidos mais tarde ao sistema partilhado chegam sem histórico, e essas cinco linhas poupam a primeira conversa de meia hora com quem os criou.

    Como documentar um componente que ainda está em beta? Com um estado explícito no topo da página: beta, estável ou descontinuado. Em beta, a página indica o que pode mudar sem aviso, por exemplo nomes de propriedades, e o que já está fechado. Isto evita que outra equipa construa um ecrã inteiro sobre uma API que muda na semana seguinte.

    A documentação deve estar em português ou em inglês? Os nomes de propriedades e tokens ficam na língua do código, quase sempre inglês. As regras de uso e os exemplos de texto ficam na língua dos produtos. Uma equipa portuguesa que lança só em pt-PT ganha em escrever as regras de microcopy em português, porque o comprimento das etiquetas muda com a língua.

    A escolha de fundo é entre uma página curta que cobre 80% das dúvidas e fica atualizada, e uma página exaustiva que cobre tudo durante dois meses. A curta perde nos casos raros, que vão continuar a chegar ao canal de suporte. A exaustiva perde em tudo o resto a partir da primeira release que ninguém documentou. Para um sistema com menos de três pessoas dedicadas, a página curta ganha quase sempre; a exaustiva só compensa quando há alguém pago para a manter.

    Artigos relacionados