Marcus Andrey Estudo
Read in English Biblioteca

Design systems · Passo 6 · 7 min de leitura

Documentação de componentes que as pessoas usam

A maior parte da documentação de design systems é escrita para quem construiu o sistema, não para quem está com prazo. O que a página de um componente precisa responder, em que ordem, onde cada parte mora (site de documentação, Figma, Storybook), como os melhores sistemas públicos organizam as suas, e como manter a documentação verdadeira.

Um fichário de argolas aberto, deitado sobre as capas, com sete páginas impressas em três argolas. Passe o ponteiro por cima e as páginas viram junto, a que está sob o ponteiro se soltando da pilha e se erguendo na direção dele. Este passo é isso: a documentação só vale o que as pessoas encontram nela, então precisa abrir na página de que elas precisam. Este passo tem três lições: documentação de componentes que as pessoas usam, como trazer os times para o sistema e como medir a adoção.Ilustração: Marcus Andrey, desenhada com Hairline (MIT, Lucas Marques).

Ninguém lê uma página de documentação de cima para baixo. As pessoas chegam com uma pergunta e saem assim que ela é respondida. "Posso usar isto aqui?" "Qual eu escolho?" "Isto é acessível?" Uma boa página se organiza em torno dessas perguntas, na ordem em que as pessoas fazem. Uma página organizada em torno de como o componente foi construído responde perguntas que ninguém fez, e esconde aquela que trouxe a pessoa até ali.

O que você vai conseguir fazer depois de ler:

  • Listar as perguntas que a página de um componente precisa responder, em ordem
  • Escrever "quando usar" e "quando não usar" que resolvem decisões
  • Decidir o que mora no site de documentação, no Figma e no Storybook
  • Manter a documentação honesta com um responsável, um status e uma data de revisão

1. As perguntas com que as pessoas chegam

Quem lê a página do Button, e por quê:

  • Uma designer no meio do fluxo: "Isto deveria ser um botão ou um link? Qual variante?"
  • Um dev construindo: "Quais são as props? Qual é o import? O que acontece com um rótulo longo?"
  • Quem revisa ou testa: "É acessível? Como funciona no teclado?"
  • Uma gerente de produto: "Isto é estável, ou vai mudar debaixo da gente?"

Então a página precisa responder, mais ou menos nesta ordem: o que é, devo usar aqui, como usar bem, como construir, é acessível, e posso confiar. O resto é opcional.


2. Uma página, preenchida

Harbour › Componentes › Button

Button Estável 3.0.0

Use um botão para começar uma ação: reservar, salvar, fazer check-in, cancelar. Para ir para outra página, use um link.

  • Uso
  • Design
  • Código
  • Acessibilidade
  • Changelog
Reservar travessiaVer horáriosCancelar reserva

Quando usar

  • Para enviar um formulário ou confirmar uma etapa
  • Primário: a única ação principal de uma tela
  • Danger: ações que não têm volta, sempre com confirmação

Quando não usar

  • Para navegar: use um link, mesmo que pareça um botão
  • Para mais de três ações lado a lado: use um menu
  • Para ligar e desligar uma configuração: use um switch
Faça
Reservar travessiaVer horários

Um primário por tela. A segunda ação é secundária.

Não faça
Reservar travessiaVer horários

Dois primários competem, e a pessoa trava no botão, não na decisão.

Acessibilidade

  • Feito sobre o <button> nativo: teclado e leitor de tela funcionam sem código extra
  • Pelo menos 44 px de altura no tamanho padrão; o compacto tem 32 px, só para o console no desktop
  • Contraste medido: primário 6,35:1 (claro), 5,32:1 (escuro); danger 5,14:1 (claro)
  • Botões desativados não recebem foco: diga ao lado por que a ação não está disponível

Responsável: time do HarbourFigma: Harbour Components › ButtonStorybook: Button · 8 storiesCode Connect: conectadoÚltima revisão em 6 out. 2026

Uma página de documentação preenchida para o Button do Harbour, na aba Uso. Ela responde às perguntas com que as pessoas chegam, na ordem em que perguntam: o que é isto, devo usar aqui, como usar bem, e é seguro. O rodapé liga o mesmo componente no Figma, no Storybook e no código, então a página é o ponto de encontro, não uma quarta cópia.

O que cada parte faz na página do Button do Harbour:

  • Uma frase de propósito embaixo do título, dizendo também o que usar no lugar: "Para ir para outra página, use um link."
  • Um status e uma versão ao lado do título. "Estável 3.0.0" responde à gerente de produto em duas palavras.
  • Um exemplo vivo no topo, com as cores reais do Harbour, no claro e no escuro.
  • Quando usar, quando não usar. A maior parte do valor está na segunda lista, porque ela aponta a alternativa.
  • Faça e não faça, com conteúdo real da Tidewater, não "Lorem ipsum". Uma imagem de dois primários competindo resolve mais discussões do que um parágrafo.
  • Acessibilidade: o que o componente resolve para você, o que ainda fica com você, e o contraste medido.
  • Um rodapé de links para o mesmo componente no Figma, no Storybook e no código, com o responsável e a data da última revisão.

Escrever uma página dessas você mesmo é o laboratório Escreva a página de documentação de um componente.


3. Como os sistemas públicos fazem

Dois sistemas bem documentados, duas estruturas que valem a cópia:

  • O GOV.UK Design System coloca cada componente numa página longa: "When to use this component" (quando usar), "How it works" (como funciona), depois "Research on this component" (pesquisa sobre o componente), "Recent changes" (mudanças recentes) e "Help improve this component" (ajude a melhorar) (GOV.UK Design System, Button). A seção de pesquisa é rara e valiosa: ela diz o que foi testado e com quem, então você sabe quanto confiar na orientação.
  • O IBM Carbon divide cada componente em abas: Guidelines, Specifications, Code e Accessibility (Carbon, Button). As abas funcionam para um público grande, em que design e desenvolvimento querem coisas diferentes da mesma página.

Nenhum dos dois serve para todo mundo. Um sistema pequeno como o Harbour começa com uma página e acrescenta abas quando ela fica longa demais para passar os olhos. O que os dois têm em comum é a ordem: quando e por que primeiro, como depois, os detalhes por último.


4. Onde cada parte mora

A documentação não precisa morar num lugar só, mas cada fato deveria morar em um lugar, com links a partir dos outros:

Onde O que mora lá Por que lá
Site de documentação Propósito, quando usar, faça e não faça, regras de conteúdo, acessibilidade, status Todo mundo lê, sem ferramenta nem assento
Figma Uma descrição curta do componente e um link para a página Quem desenha vê no painel de assets, na hora de escolher
Storybook Todos os estados, a tabela de props, exemplos vivos Gerado a partir do código, então não fica velho (Storybook e documentação viva)
Dev Mode O trecho de código real, via Code Connect Quem desenvolve vê enquanto inspeciona (Code Connect e a ponte entre design e código)
Changelog O que mudou, por versão Um histórico só para o sistema inteiro (Versões e releases)

O erro comum é o contrário: a mesma regra de uso escrita em quatro lugares, cada uma um pouco diferente, e ninguém sabe qual é a atual.


5. Manter a documentação verdadeira

  • Um responsável por página, com nome ou time, mostrado na página.
  • Uma data de "última revisão". Uma página revisada há três anos avisa o leitor para conferir.
  • A documentação muda na mesma versão que o componente. Uma prop nova sem a sua linha na documentação não está lançada.
  • Um jeito de perguntar e de reclamar, na própria página. O "Help improve this component" do GOV.UK é o modelo. A pergunta de exemplo de Brad Frost para uma pesquisa sobre o sistema também vale a cópia: "On a scale from one to five, how useful is the pattern documentation? Any suggestions?", de um a cinco, quanto a documentação é útil, e alguma sugestão? (Brad Frost, Atomic Design, capítulo 5).
  • Veja o que as pessoas buscam no site de documentação. Uma busca sem resultado é uma página que você ainda não escreveu.

Movimento e imagens precisam do mesmo cuidado: veja Documentar o movimento num design system e Um guia de estilo de imagem no seu design system.


6. Erros comuns

  • Páginas que começam pela anatomia e pelas especificações, e só chegam ao "quando usar" no fim.
  • "Quando não usar" faltando, ou sem alternativa.
  • Exemplos de faça e não faça com texto de preenchimento.
  • A mesma regra no site, no Figma e numa apresentação, todas um pouco diferentes.
  • Nenhum status, e as pessoas não distinguem um componente estável de um experimento.
  • Documentação escrita uma vez no lançamento e nunca revisada.

7. Vocabulário

Termo Significado
Página de documentação A página que explica um componente: propósito, uso, código, acessibilidade
Orientação de uso Quando usar, quando não usar, e como usar bem
Faça e não faça Um par de exemplos que mostra o uso certo e o errado
Status O quanto um componente está assentado: experimental, estável, descontinuado
Fonte única Cada fato escrito num lugar só, com links a partir dos outros

8. Experimente (sem ferramentas)

  1. Escolha um componente do seu produto e escreva a pergunta que uma pessoa do design faria sobre ele hoje.
  2. Abra a página de documentação dele, ou pergunte onde está. Cronometre quanto tempo leva para achar a resposta.
  3. Escreva a linha de "quando não usar" que teria respondido, com a alternativa.

Perguntas para refletir: Que parte da documentação do seu time está escrita em mais de um lugar? Quem perceberia se uma página estivesse errada?


9. Se você já pratica

  • Reorganize as páginas mais visitadas para o "quando usar" vir antes das especificações.
  • Acrescente status, responsável e data da última revisão a toda página.
  • Acrescente uma seção de pesquisa a um componente, mesmo que sejam duas linhas sobre o que vocês testaram.
  • Revise todo mês as buscas sem resultado do site de documentação.

Checklist

Para saber mais

Livros, cursos e vídeos para ir mais fundo

Os links dos livros são de afiliado da Amazon: como associado, recebo por compras qualificadas, sem custo a mais para você.

Relacionadas

Escreva a página de documentação de um componente · Storybook e documentação viva · Conteúdo e voz no sistema · Documentar o movimento num design system · O que é um design system · Modelo de página de componente

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar