Documentação de componentes: anatomia, comportamento, regras de uso e exemplos

O que é documentação de componentes (e por que ela evita ruído)

Documentação de componentes é o conjunto de informações que descreve como um componente deve ser entendido, usado e implementado. Ela conecta três perspectivas: (1) a intenção de design (o “porquê” e o “quando”), (2) o comportamento esperado (o “como se comporta” em estados e interações) e (3) as regras de uso (o “pode/não pode” e as decisões que não devem ficar a cargo de cada pessoa). Sem documentação, o componente vira apenas um desenho reutilizável; com documentação, ele vira um contrato entre design, produto e engenharia.

Uma boa documentação reduz retrabalho porque antecipa dúvidas comuns: “posso usar esse botão dentro de um card clicável?”, “qual o texto máximo do chip?”, “quando usar tooltip vs helper text?”, “o que acontece quando não há dados?”. Ela também acelera handoff: quem implementa não precisa inferir comportamento a partir de frames soltos, e quem mantém o sistema consegue avaliar impacto de mudanças.

Estrutura recomendada para documentar um componente

Para manter consistência, use um template fixo para todos os componentes. Abaixo está uma estrutura prática que funciona bem em Design Systems e pode ser aplicada em páginas de documentação dentro do próprio arquivo do Figma (ou em uma ferramenta externa, se existir), sem depender de “memória do time”.

• Resumo: o que é e qual problema resolve.
• Anatomia: partes do componente e nomes padronizados.
• Comportamento: estados, interações, responsividade e regras de conteúdo.
• Regras de uso: quando usar, quando não usar, do’s & don’ts.
• Exemplos: casos comuns e casos-limite (edge cases).
• Conteúdo e redação: orientações de texto, limites e tom (quando aplicável).
• Implementação: API esperada (props), eventos, dependências e considerações técnicas.
• Checklist: itens para revisar antes de liberar/atualizar o componente.

Anatomia: como descrever as partes do componente

Anatomia é a “lista de peças” do componente. Ela deve ser objetiva, nomear cada parte e explicar o papel de cada uma. O objetivo é que qualquer pessoa consiga apontar para uma parte específica e falar a mesma língua: “ícone leading”, “label”, “supporting text”, “container”, “divider”, “action slot”.

O que incluir na anatomia

• Partes obrigatórias: elementos que sempre existem (ex.: container, label).
• Partes opcionais: elementos condicionais (ex.: ícone, badge, helper text).
• Slots: áreas onde outros elementos podem entrar (ex.: “right slot” para ação).
• Hierarquia: o que é conteúdo vs decoração vs ação.
• Relações: alinhamentos e espaçamentos relevantes (sem reexplicar tokens/estilos).

Exemplo de anatomia (Botão)

Use um formato consistente, como lista numerada ou tabela (se sua ferramenta permitir). Em HTML simples, uma lista funciona bem:

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

• Container: área clicável; define altura mínima e padding.
• Label: texto principal do botão; deve ser curto e orientado a ação.
• Ícone leading (opcional): ícone antes do texto; usado para reforçar significado.
• Ícone trailing (opcional): ícone após o texto; usado para indicar navegação/expansão.
• Indicador de carregamento (opcional): substitui ícone e/ou label conforme regra de loading.

Na documentação, inclua também uma imagem/variação visual do componente com callouts (setas e números) apontando para cada parte. O texto deve referenciar os mesmos números para evitar ambiguidade.

Regras práticas para nomear partes

• Evite nomes baseados em aparência (“coisa azul”, “linha de cima”). Prefira função (“divider”, “supporting text”).
• Use “leading/trailing” em vez de “left/right” quando o componente pode ser usado em idiomas RTL.
• Se houver slots, documente o que é permitido dentro deles (ex.: “apenas ícone” vs “ícone + contador”).

Comportamento: estados, interações e regras que afetam o usuário

Comportamento descreve como o componente reage a ações, mudanças de estado e variações de conteúdo. É aqui que a documentação evita interpretações divergentes entre design e engenharia. Mesmo que protótipos existam, o texto é necessário para registrar regras e prioridades (“se A e B acontecerem, qual estado vence?”).

Estados essenciais para documentar

• Default: aparência e comportamento padrão.
• Hover: feedback ao passar o mouse (quando aplicável).
• Pressed/Active: feedback durante clique/toque.
• Focus: como o foco aparece e quando é aplicado.
• Disabled: quando usar, o que acontece com eventos e acessibilidade.
• Loading: o que bloqueia, o que permanece visível, duração e prevenção de cliques repetidos.
• Selected/Checked: para componentes de seleção.
• Error/Warning/Success: para inputs e feedbacks.

Prioridade de estados (regra de precedência)

Um erro comum é não definir o que acontece quando estados se sobrepõem. Documente explicitamente uma ordem de prioridade. Exemplo genérico:

Prioridade sugerida (do mais forte para o mais fraco): Disabled > Loading > Error > Focus > Hover > Default

Adapte por componente. Para um input, “Error” pode ter prioridade visual sobre “Focus”, mas o foco ainda precisa ser perceptível. A documentação deve dizer como conciliar (ex.: borda de erro + anel de foco).

Interações e eventos

Liste as interações suportadas e o resultado esperado. Isso ajuda a alinhar microdecisões, como “clique no container inteiro” vs “apenas no ícone”.

• Click/Tap: o que dispara; se há prevenção de múltiplos cliques.
• Keyboard: teclas relevantes (Enter, Space, Esc, setas).
• Pointer: hover, pressed, drag (se aplicável).
• Gestos: swipe, long press (mobile, se aplicável).

Regras de conteúdo (content rules)

Componentes quebram mais por conteúdo do que por layout. Documente limites e comportamento quando o conteúdo extrapola.

• Comprimento de texto: máximo recomendado e o que acontece ao exceder (quebra de linha, truncamento, expansão).
• Quebra de linha: permitido ou não; se permitido, quantas linhas.
• Ícones: quando usar, quando evitar redundância (ícone + texto repetindo).
• Imagens/avatares: fallback quando não há imagem (iniciais, placeholder).
• Números: formatação e limites (ex.: contador “99+”).

Regras de uso: quando usar, quando não usar, e combinações proibidas

Regras de uso transformam “opções” em decisões consistentes. Elas devem ser prescritivas. Se tudo é permitido, nada é padrão.

Quando usar

Explique o contexto ideal. Exemplo para um componente “Badge”:

• Use para destacar um status curto (ex.: “Novo”, “Beta”, “Pago”).
• Use em listas e cards para facilitar varredura visual.
• Use quando o status não precisa de ação imediata.

Quando não usar

• Não use para mensagens longas; prefira um componente de alerta.
• Não use como botão; se precisa de clique, use chip/ação apropriada.
• Não use múltiplos badges em sequência se isso competir com o conteúdo principal.

Do’s & Don’ts com exemplos

Inclua exemplos visuais na documentação e descreva em texto o motivo. Mesmo sem imagem, registre a regra:

• Do: “Novo” (1 palavra), cor de status consistente.
• Don’t: “Este item é novo e foi atualizado ontem” (frase longa).

Combinações e dependências

Documente combinações permitidas e proibidas com outros componentes. Exemplo para “Card”:

• Card clicável: não permitir botão primário dentro do card inteiro clicável (conflito de ação). Alternativa: tornar apenas uma área clicável ou usar link secundário.
• Card com menu: se houver “more actions”, definir área de clique separada para não competir com o clique do card.

Exemplos: do caso comum ao caso-limite

Exemplos são a parte mais consultada da documentação. Eles devem cobrir: (1) uso padrão, (2) variações comuns, (3) edge cases, (4) anti-exemplos. Sempre que possível, descreva o cenário e a intenção, não só a aparência.

Checklist de exemplos que valem a pena incluir

• Vazio: sem dados (ex.: lista vazia, avatar sem foto).
• Carregando: skeleton/spinner e bloqueio de interação.
• Erro: mensagem e recuperação (tentar novamente, editar campo).
• Conteúdo extremo: texto muito longo, nomes compostos, números grandes.
• Internacionalização: textos maiores em outros idiomas e formatos de data/moeda (se aplicável).

Exemplo detalhado (Input de texto)

Em vez de apenas mostrar estados, descreva regras:

• Label: obrigatório; se não houver, o input não deve ser usado (evita ambiguidade).
• Placeholder: opcional; não substitui label; usado para exemplo de formato.
• Helper text: opcional; usado para instruções curtas.
• Error message: aparece abaixo; deve orientar correção (“Use um e-mail válido”).
• Contador: se houver limite de caracteres, mostrar “x/limite”.

Inclua exemplos de texto:

Label: E-mail corporativo (obrigatório)
Placeholder: nome@empresa.com
Helper: Use seu e-mail de trabalho
Erro: Informe um e-mail válido (ex.: nome@empresa.com)

Observação: ao transformar isso em documentação visual, mostre os quatro estados lado a lado e inclua um exemplo com texto longo para validar truncamento/quebra.

Passo a passo prático: como documentar um componente no Figma sem criar bagunça

O objetivo do passo a passo é criar uma página de documentação que seja fácil de manter e difícil de interpretar errado. O foco aqui é o conteúdo e a organização da informação na página do componente, não a estrutura geral do arquivo (que já foi tratada em capítulos anteriores).

1) Defina o “contrato” do componente em uma frase

Escreva um resumo de 1–2 linhas que responda: o que é e quando usar. Exemplo:

Botão: aciona uma ação imediata. Use para ações principais e secundárias em fluxos.

Isso evita que o componente seja usado como “link”, “tab” ou “chip” por conveniência.

2) Crie uma seção de anatomia com callouts

Monte uma instância do componente em tamanho típico e adicione marcadores numerados apontando para cada parte. Ao lado, liste os itens com o mesmo número e nome. Inclua observações curtas, como “opcional” e “não usar sem label”.

• Se o componente tiver slots, mostre pelo menos 2 exemplos preenchendo o slot (ex.: ícone e contador) para deixar claro o que é permitido.
• Se houver variações estruturais (ex.: com/sem supporting text), documente como anatomias relacionadas, não como componentes diferentes (a menos que sejam de fato diferentes).

3) Documente estados com uma matriz (state matrix)

Crie uma grade com colunas para estados e linhas para variações relevantes (ex.: tamanho, hierarquia, tipo). O importante é que a pessoa consiga comparar rapidamente.

Matriz sugerida (exemplo para Botão):
Linhas: Primary / Secondary / Tertiary
Colunas: Default / Hover / Pressed / Focus / Disabled / Loading

Ao lado da matriz, escreva regras de precedência e notas de comportamento (ex.: “Loading desabilita clique e mantém largura”).

4) Escreva regras de uso como decisões, não como possibilidades

Transforme discussões recorrentes em regras. Exemplos para Botão:

• Use Primary para a ação principal da tela; no máximo 1 por contexto.
• Use Secondary para ações alternativas relevantes.
• Use Tertiary para ações de baixa ênfase (ex.: “Cancelar”).
• Não use botão com texto muito longo; reescreva o rótulo ou mude o padrão de UI.

Se houver exceções, documente explicitamente: “Exceção: em modais com duas ações, Primary + Secondary é permitido”.

5) Adicione exemplos prontos para copiar (com contexto)

Crie pequenos blocos de UI com o componente em contexto (ex.: em um header, em um formulário, em um card). Cada exemplo deve ter uma legenda curta: “Por que esse é o padrão”. Inclua pelo menos um exemplo de edge case.

• Exemplo padrão: botão primário no final de formulário.
• Edge case: botão com ícone leading e label curto; loading mantendo largura.
• Anti-exemplo: dois botões primários lado a lado (registrar como não permitido).

6) Documente a API esperada (para handoff)

Mesmo que a implementação seja em outra stack, descreva as propriedades e eventos esperados em linguagem neutra. Isso ajuda a engenharia a mapear para props reais e evita divergências.

Botão (API conceitual):
- variant: primary | secondary | tertiary
- size: sm | md | lg
- iconLeading: boolean (ou nome do ícone)
- iconTrailing: boolean
- disabled: boolean
- loading: boolean
- onClick: evento
Regras:
- disabled e loading não podem ser true ao mesmo tempo (loading tem prioridade)
- se loading=true, bloquear onClick e manter largura

Para componentes de formulário, inclua: value, defaultValue, onChange, onBlur, validationState, errorMessage. Para componentes de navegação, inclua: selected, onSelect, href, target.

7) Inclua um checklist de revisão do componente

Checklist reduz regressões quando alguém altera o componente. Exemplo genérico:

• Estados principais revisados (default, hover, pressed, focus, disabled, loading).
• Regras de conteúdo testadas com textos longos e curtos.
• Exemplos atualizados (padrão e edge cases).
• API conceitual revisada (props/eventos) e alinhada com engenharia.
• Notas de migração registradas (se mudou comportamento).

Como escrever documentação que o time realmente usa

Documentação útil é escaneável e orientada a decisão. Algumas práticas aumentam adoção:

• Comece pelo “quando usar”: é a dúvida mais frequente.
• Use linguagem prescritiva: “use”, “não use”, “limite”, “permitido”.
• Evite jargão interno: se precisar, defina rapidamente.
• Registre trade-offs: quando houver exceção, explique o motivo e o risco.
• Inclua edge cases: eles evitam bugs e decisões improvisadas.

Modelos prontos (templates) para copiar e adaptar

Template de seção: Anatomia

Anatomia
1. Container — função e comportamento (clique, padding, altura mínima)
2. Label — regras de texto (curto, verbo de ação)
3. Supporting text (opcional) — quando usar
4. Leading icon (opcional) — quando usar / quando evitar
5. Trailing slot (opcional) — o que pode entrar (ícone, contador, menu)

Template de seção: Comportamento

Comportamento
- Estados: Default, Hover, Pressed, Focus, Disabled, Loading
- Precedência de estados: ...
- Interações: clique/toque, teclado, atalhos (se houver)
- Conteúdo: truncamento, quebra de linha, limites
- Responsividade: como se adapta em larguras menores (ex.: label quebra? ícone some?)

Template de seção: Regras de uso

Regras de uso
Use quando: ... (3–5 bullets)
Não use quando: ... (3–5 bullets)
Do: ...
Don’t: ...
Combinações: permitido/proibido com outros componentes

Template de seção: Exemplos

Exemplos
- Padrão: cenário + porquê
- Variação comum: cenário + porquê
- Edge case: cenário + regra aplicada
- Anti-exemplo: cenário + risco