Design systems · Laboratórios · 5 min de leitura
Escreva a página de documentação de um componente
Um laboratório guiado: escreva a página de documentação de um componente, na ordem em que as pessoas fazem as perguntas. Junte as perguntas reais, preencha um modelo, escreva regras de uso com motivo e teste a página com um designer e um dev que nunca usaram o componente. Cerca de duas horas.
Uma página de documentação é lida por alguém com pressa, no meio de uma tela, com uma pergunta só. Se a resposta está na primeira tela, a pessoa usa o componente do jeito certo. Se está no sexto parágrafo, ela chuta, pergunta no chat ou faz o próprio. Você vai escrever uma página para um componente, começando pelas perguntas que as pessoas fazem de verdade, e testá-la com duas pessoas que nunca o usaram.
O que você vai fazer:
- Juntar as perguntas reais que as pessoas fazem sobre um componente
- Preencher um modelo de página de documentação, de cima para baixo
- Escrever regras de uso com um motivo e um exemplo
- Testar a página com um designer e um dev
Você vai precisar de: um componente do seu sistema (ou o Notice do Harbour, como no exemplo), um lugar para escrever (a sua ferramenta de documentação, um arquivo Markdown ou uma página no Figma), um histórico de chat ou de tickets para pesquisar, cerca de duas horas.
1. Junte as perguntas
Antes de escrever, procure o nome do componente no chat do time, nos tickets e nas revisões de design. Anote cada pergunta que encontrar, palavra por palavra. Para um aviso, elas soam assim:
- "Posso usar isso para um erro de formulário?"
- "Pode ter um botão?"
- "Qual eu uso para 'travessia cancelada'?"
- "O leitor de tela lê em voz alta?"
Ordene pela frequência. As três primeiras vão para a primeira tela da página.
2. Use um modelo, na ordem em que as pessoas perguntam
- Notice
- Uso
- Propriedades
- Acessibilidade
- Conteúdo
- Changelog
NoticeEstável · desde a 3.2.0Figma · React · Storybook
Avisa as pessoas sobre algo que afeta a página ou a tarefa inteira, sem interromper.
Quando usar, e quando não
Dialog).Propriedades
tone: info, success, warning, danger · title: texto · dismissible: booleana · action: slot, no máximo um link ou botão.
Acessibilidade
- Renderizado com
role="status"; avisosdangerque aparecem depois de uma ação usamrole="alert". - O tom está nas palavras além da cor: o título diz o que aconteceu.
- Texto 15,58:1 sobre
sand.50; a borda coral é decoração, não a mensagem.
As páginas de componente do GOV.UK Design System abrem com quando usar o componente, depois como ele funciona, depois a pesquisa por trás dele (GOV.UK Design System, Button). A ordem importa mais do que os títulos exatos. Copie este modelo:
# Nome do componente [status · desde a versão] [Figma] [Código] [Storybook]
Uma frase: o que ele faz por quem usa o produto.
[Exemplo ao vivo, configuração padrão]
## Quando usar
## Quando não usar (e o que usar no lugar)
## Como funciona
Variantes e propriedades, cada uma com um exemplo
## Acessibilidade
Papel (role), teclado, o que é anunciado, contraste
## Conteúdo
Como escrever o texto dentro dele
## Pesquisa e decisões
## Changelog
Deixe na primeira tela só o nome, o status, a frase, o exemplo e o "quando usar / quando não usar". É disso que a maioria das visitas precisa.
3. Escreva regras de uso que as pessoas seguem
Cada regra precisa de três coisas:
- A regra, como algo que dá para conferir: "Um aviso por página", e não "use com moderação".
- O motivo, em uma linha: "Dois avisos competem, e as pessoas não leem nenhum."
- Um exemplo: um faça e um não faça, como imagens ou exemplos ao vivo.
No "quando não usar", sempre diga a alternativa. "Não use para erros num campo: use a mensagem de erro do campo" ajuda. "Não use para erros" deixa a pessoa sem saída.
4. Escreva a seção de acessibilidade para os dois leitores
Designers precisam saber o que têm que fornecer; devs precisam saber o que o componente faz. Para um aviso:
- Papel:
role="status"para informação que chega sem interromper,role="alert"só para mensagens importantes e urgentes. O padrão de alerta do APG descreve alertas como informação importante e potencialmente urgente, e avisa que interrupções frequentes atrapalham a usabilidade para pessoas com deficiências visuais e cognitivas (WAI-ARIA APG, Alert). - Não só pela cor: o tom precisa ficar claro também pelas palavras (W3C, Understanding 1.4.1).
- Contraste: a razão medida do texto sobre o fundo, por escrito. O
ink.900sobresand.50do Harbour dá 15,58:1.
5. Escreva as propriedades e o changelog
Liste cada propriedade com os valores e o padrão, com os mesmos nomes do Figma e do código (veja Desenhe um componente com variantes no Figma). Se você tem Storybook, aponte para a story ou incorpore os controles dela em vez de copiar a tabela à mão, para que ela não fique desatualizada (veja Storybook e documentação viva).
O changelog no fim da página responde "isso mudou desde a última vez que usei?". Uma versão, uma data, uma linha cada.
6. Teste a página
Entregue a página a um designer e um dev que não usaram o componente. Dê uma tarefa a cada um:
- Designer: "Coloque um aviso nesta tela dizendo que a travessia das 08:40 está atrasada."
- Dev: "Implemente, e me diga o que um leitor de tela vai falar."
Observe, não ajude. Cada vez que a pessoa rolar procurando algo, ou te perguntar, anote a pergunta. Essa pergunta é uma linha que falta, ou uma linha no lugar errado.
7. Confira seu trabalho
Perguntas para refletir: Qual pergunta apareceu mais, e ela já tinha resposta em algum lugar onde ninguém olhou? O que você tiraria da página se ela só pudesse ter metade do tamanho?
Relacionadas
Documentação de componentes que as pessoas usam · Storybook e documentação viva · Conteúdo e voz no sistema · Documentar o movimento num design system · Componentes acessíveis · Modelo de página de componente