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.
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
Um primário por tela. A segunda ação é secundária.
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
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)
- Escolha um componente do seu produto e escreva a pergunta que uma pessoa do design faria sobre ele hoje.
- Abra a página de documentação dele, ou pergunte onde está. Cronometre quanto tempo leva para achar a resposta.
- 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
- GOV.UK Design System, Button
- Carbon Design System, Button
- Brad Frost, Atomic Design, capítulo 5: Maintaining design systems
Livros, cursos e vídeos para ir mais fundo
- Design SystemsAlla KholmatovaLivro · Smashing Magazine, 2017 (Amazon)
- Expressive Design SystemsYesenia Perez-CruzLivro · A Book Apart, 2019 (Amazon)
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