Framework · Design systems · 4 min de leitura
Modelo de página de componente
A página de um componente na ordem em que as pessoas perguntam: nome e status, uma frase, um exemplo vivo, quando usar e quando não, como funciona, acessibilidade, conteúdo, pesquisa e changelog, com cada informação num lugar só e linkada dos outros.
Nome, status e versão, com links para Figma, código e Storybook.
"Estável 3.0.0"Uma frase do que ele faz, e o que usar no lugar.
"Para ir a uma página, use um link"Um exemplo vivo com as opções padrão, no claro e no escuro.
Conteúdo real, nunca Lorem ipsumOnde ele cabe e onde não cabe, com o nome da alternativa.
O valor está no "não"Variantes e propriedades, linkadas do Storybook, não copiadas.
Mesmos nomes do Figma e do códigoPapel, teclado, o que é anunciado e o contraste medido.
Para designers e engenheirosComo escrever o texto dentro dele, com um exemplo real.
O que mudou, o que fazerO que foi testado e o changelog, depois dono e data de revisão.
"Revisado em …"Use quando
- Você vai escrever a página de um componente novo, ou reescrever uma que ninguém lê.
- A mesma pergunta sobre um componente volta sempre no chat.
- Uma regra de uso vive em quatro lugares, cada um um pouco diferente, e ninguém sabe qual vale.
Como usar
- Junte primeiro as perguntas reais. Procure o nome do componente no chat, nos tickets e nas revisões de design, e anote cada pergunta palavra por palavra. Ordene pela frequência. Resultado: as três perguntas que a primeira tela precisa responder.
- Preencha a primeira tela. Nome, status e versão, uma frase de propósito que diz o que usar no lugar, um exemplo vivo, e depois "quando usar" e "quando não usar". Resultado: uma primeira tela com que um designer consegue agir sem rolar.
- Escreva cada regra com motivo e exemplo. Uma regra que dá para conferir ("um aviso por página"), uma linha de porquê, um faça e um não faça com conteúdo real. Todo "não faça" diz o que usar no lugar. Resultado: regras de uso que as pessoas seguem.
- Escreva a acessibilidade para os dois leitores. Papel, teclado, o que é anunciado e o contraste medido: o que o componente faz por você e o que você ainda precisa fazer. Resultado: uma seção de acessibilidade que serve de referência para quem testa.
- Linke os detalhes em vez de copiar. As propriedades vêm do Storybook ou do código, o trecho de código do Dev Mode, o histórico do changelog. Uma informação, um lugar. Resultado: uma página que não se desencontra do componente.
- Teste a página com duas pessoas. Dê uma tarefa a um designer e a um engenheiro que ainda não usaram o componente. Cada vez que alguém rola procurando algo, falta uma linha ou ela está no lugar errado. Resultado: pelo menos uma linha mudada.
Exemplo
A página do Notice do Harbour, depois que o time juntou as perguntas do chat. As três mais comuns eram "Posso usar para erro de formulário?", "Qual eu uso para 'saída cancelada'?" e "O leitor de tela lê em voz alta?".
| Parte | O que o Harbour escreveu |
|---|---|
| Linha do título | Notice · Estável 2.1.0 · links para Figma, código e Storybook |
| Uma frase | Avisa as pessoas de algo nesta página sem interromper. Para um erro num campo, use a mensagem de erro do campo |
| Quando usar | Informação que afeta a página inteira: uma saída atrasada, um horário mudado |
| Quando não usar | Erros num campo (mensagem de erro do campo); ações que pedem resposta (diálogo) |
| Acessibilidade | role="status"; role="alert" só para mensagens urgentes e com prazo; o tom fica claro pelas palavras, não só pela cor; texto 15,58:1 sobre o fundo |
| Conteúdo | Comece pelo que mudou e pelo que fazer: "A saída das 08:40 sai às 09:10. Sua reserva continua valendo." |
| Rodapé | Dono, data da última revisão, link "Ajude a melhorar este componente" |
O engenheiro do teste achou o papel em menos de um minuto. O designer perguntou onde estava o exemplo da saída cancelada, e ele subiu para "quando usar".
Cuidado com
- Anatomia primeiro. Páginas que abrem com especificações e chegam ao "quando usar" no fim respondem primeiro o que ninguém perguntou.
- "Quando não usar" sem alternativa. "Não use para erros" deixa a pessoa sem saída. Diga o que usar.
- Exemplos com texto de enchimento. Faça e não faça com "Lorem ipsum" não encerram discussão. Use conteúdo real do produto.
- Sem dono, sem data. Uma página sem dono e sem data de revisão envelhece em silêncio. Mostre os dois, e atualize a página no mesmo lançamento do componente.
Modelo
Copie para a sua ferramenta de documentação ou para um arquivo Markdown e preencha de cima para baixo.
# Nome do componente [status · desde a versão] [Figma] [Código] [Storybook]
Uma frase: o que ele faz pela pessoa que usa o produto.
Para ..., use ... no lugar.
[Exemplo vivo, opções padrão, claro e escuro]
## Quando usar
- ...
## Quando não usar (e o que usar no lugar)
- ... → use ...
## Como funciona
Variantes e propriedades, cada uma com um exemplo (do Storybook, não copiadas)
## Acessibilidade
Papel: ... Teclado: ... Anunciado: ... Contraste: ...:1
O componente cuida de: ... Você ainda precisa: ...
## Conteúdo
Como escrever o texto dentro dele, com um exemplo real
## Pesquisa e decisões
O que foi testado, com quem, e o que mudou
## Changelog
versão · data · uma linha
Dono: ... Última revisão: ... [Perguntar ou relatar um problema]
- Design SystemsAlla KholmatovaLivro · 2017 (Amazon)
- Expressive Design SystemsYesenia Perez-CruzLivro · 2019 (Amazon)
- Atomic DesignBrad FrostLivro · 2016 (Amazon)
- ButtonGOV.UK Design System (site externo)
- ButtonCarbon (site externo)
- Alert patternWAI-ARIA APG (site externo)
- Maintaining design systemsAtomic Design, capítulo 5 (site externo)
Os links "Ver na Amazon" são de afiliado: como associado, recebo por compras qualificadas, sem custo a mais para você.