Marcus Andrey Estudo
Read in English Biblioteca

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.

1Nome, status

Nome, status e versão, com links para Figma, código e Storybook.

"Estável 3.0.0"
2Propósito

Uma frase do que ele faz, e o que usar no lugar.

"Para ir a uma página, use um link"
3Exemplo

Um exemplo vivo com as opções padrão, no claro e no escuro.

Conteúdo real, nunca Lorem ipsum
4Quando, quando não

Onde ele cabe e onde não cabe, com o nome da alternativa.

O valor está no "não"
5Como funciona

Variantes e propriedades, linkadas do Storybook, não copiadas.

Mesmos nomes do Figma e do código
6Acessibilidade

Papel, teclado, o que é anunciado e o contraste medido.

Para designers e engenheiros
7Conteúdo

Como escrever o texto dentro dele, com um exemplo real.

O que mudou, o que fazer
8Pesquisa, histórico

O que foi testado e o changelog, depois dono e data de revisão.

"Revisado em …"
As partes da página de um componente na ordem em que as pessoas perguntam; as quatro primeiras ocupam a primeira tela.

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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]
Fonte
Estrutura da página de componente: GOV.UK Design System (quando usar, como funciona, pesquisa, mudanças recentes) e IBM Carbon (abas Guidelines, Specifications, Code, Accessibility). Padrão de alerta: W3C, WAI-ARIA Authoring Practices Guide. Pergunta de pesquisa sobre a documentação: Brad Frost, Atomic Design, capítulo 5

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

Salvo só neste dispositivo.

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