Documentação de design system: o que a página de cada componente precisa dizer

Design system · Artigo

Documentação de design system: o que a página de cada componente precisa dizer

Falar no WhatsApp
Resposta direta

A página de cada componente de um design system precisa dizer o que a peça resolve, mostrar um exemplo funcionando com código, indicar quando usar e quando não usar com a alternativa, listar variações e estados, trazer regras de texto para rótulos e mensagens, declarar limitações conhecidas e registrar as mudanças recentes, sempre na mesma ordem.

Segunda-feira, 9 horas. Uma pessoa que entrou na equipe na semana anterior precisa montar um formulário com 3 opções exclusivas. Ela abre a página do componente de opções no design system e, em poucos minutos, sabe se ele serve, como se comporta e que texto escrever na mensagem de erro. Ninguém precisou ser interrompido.

É isso que a documentação de design system faz quando funciona: responde antes da pergunta. Este artigo mostra a estrutura mínima de uma página de componente, com uso, não uso, estados, variações, exemplos, regras de texto e histórico, a partir de 2 documentações públicas que servem de referência.

O assunto vem da frente de design system, uma das 4 da seção de interfaces digitais. Lá se explica por que a documentação é uma das camadas do sistema. Aqui o assunto é a página em si: o que ela precisa dizer, em que ordem e com que tom.

Para que serve a página de um componente

A página de um componente serve para que qualquer pessoa da empresa use a peça certa, do jeito certo, sem depender de quem a desenhou.

Dois públicos na mesma página

A página atende quem desenha e quem programa. O primeiro quer saber quando usar a peça e como ela se combina com as outras. O segundo quer saber propriedades, estados e comportamento. As 2 leituras precisam chegar à mesma conclusão. Se o desenho diz uma coisa e o código diz outra, a página perde a autoridade.

Uma parte do contrato do sistema

A Nielsen Norman Group, em texto de Therese Fessenden, descreve a biblioteca de componentes como um conjunto de peças com nome, descrição, atributos ajustáveis, estados, trechos de código e tecnologias compatíveis. A página de documentação é onde esse conjunto vira acordo. O que está escrito ali é o que as equipes podem esperar da peça.

A documentação também orienta a governança

Quando a página diz claramente o que a peça faz e o que não faz, os pedidos de mudança ficam mais precisos. Uma equipe que precisa de algo fora do escrito sabe que está pedindo uma peça nova. O caminho desse pedido é descrito no artigo sobre governança de design system.

Quais seções a página de componente precisa ter?

A página precisa de um resumo, um exemplo vivo, critérios de uso e de não uso, variações e estados, regras de texto, notas de acessibilidade e um histórico de mudanças.

A ordem de uma documentação pública

O GOV.UK Design System, do governo britânico, organiza a página do botão nesta ordem: exemplos com código, quando usar, como funciona, pesquisa sobre o componente, mudanças recentes e como ajudar a melhorar. Dentro de "como funciona" ficam as variações, como botão principal, secundário, de alerta e em fundo escuro. Na página do componente de opções, há ainda uma seção própria de quando não usar.

A ordem de outra documentação pública

O Carbon Design System, da IBM, divide a documentação do botão em 4 abas: diretrizes, especificações, código e acessibilidade. As diretrizes começam por uma visão geral, com quando usar, quando não usar e variações. Depois vêm formatação, conteúdo, comportamentos, cada variação em detalhe, modificadores, peças relacionadas e referências.

Uma estrutura mínima a partir das 2

  1. Nome da peça e uma frase sobre o que ela resolve.
  2. Exemplo funcionando, com o código ao lado.
  3. Quando usar e quando não usar, com a alternativa indicada.
  4. Variações, cada uma com o papel que cumpre.
  5. Estados e comportamentos, inclusive os de erro.
  6. Regras de texto para rótulos, dicas e mensagens.
  7. Notas de acessibilidade e pesquisa feita com a peça.
  8. Mudanças recentes e canal para dúvidas e sugestões.

A estrutura não precisa ser igual em todas as empresas. Precisa ser igual em todas as páginas do mesmo sistema, para que quem consulta saiba onde procurar.

Quando usar e quando não usar: a seção que evita o erro

A seção de uso diz em que situação a peça resolve o problema; a de não uso diz quando ela atrapalha e qual peça usar no lugar.

O não uso com alternativa

A página do componente de opções do GOV.UK dá um exemplo direto: não use opções exclusivas se o usuário puder precisar escolher mais de uma. Nesse caso, a página manda para o componente de caixas de seleção. A frase resolve a dúvida e aponta o caminho, sem discurso.

Critérios concretos, e não adjetivos

"Use com moderação" não orienta ninguém. "Use no máximo 1 botão principal por tela" orienta. O GOV.UK recomenda evitar vários botões principais na mesma página e limitar os secundários. Critérios contáveis podem ser conferidos em revisão; adjetivos viram discussão.

O que costuma faltar

A maioria das páginas fracas descreve a peça e para. Falta dizer o que fazer quando o caso real não cabe na regra. Uma linha de orientação para o caso de fronteira, como uma pergunta com muitas opções, poupa a equipe de inventar uma solução local.

Mostrar o componente é fácil. A documentação começa a trabalhar quando diz em que situação ele não deve aparecer.

Estados, variações e comportamento

A página precisa mostrar cada estado da peça, explicar o papel de cada variação e descrever o comportamento em situações como clique repetido ou carregamento lento.

Os estados que não podem faltar

  • Padrão: a peça em repouso, como aparece na maior parte do tempo.
  • Foco: a peça selecionada pelo teclado, com indicação visível.
  • Ativo: o momento do toque ou do clique.
  • Erro: a peça quando o preenchimento não foi aceito, com a mensagem.
  • Desativado: quando existe, com a explicação de por que a peça não está disponível.
  • Carregando: o retorno enquanto a ação é processada.

Variações com papel definido

O Carbon descreve 5 variações de botão: principal, secundário, terciário, fantasma e de perigo, cada uma com nível de ênfase próprio. A página não só mostra as variações. Ela diz como combiná-las: usar ênfase alta e média juntas em um grupo, e não 2 botões de ênfase alta lado a lado.

Comportamento descrito, e não só desenhado

O GOV.UK documenta um comportamento que não aparece em uma imagem: a opção que impede o envio duplicado quando alguém clica 2 vezes no botão. A página avisa que o recurso depende de JavaScript e que a proteção no servidor continua necessária. É o tipo de detalhe que só a documentação escrita consegue transmitir.

O estado desativado merece cautela

O GOV.UK observa que botões desativados têm contraste baixo e podem confundir, e recomenda evitá-los, salvo quando a pesquisa justifica. O tema de como mostrar uma ação indisponível conforme o perfil de usuário é tratado na frente de interfaces de SaaS.

Regras de texto dentro do componente

A página de cada componente diz como escrever rótulos, dicas e mensagens de erro, porque o texto é parte da peça tanto quanto a cor e o espaço.

Rótulos de botão

O Carbon recomenda a fórmula verbo mais substantivo, como "Adicionar usuário", com exceção de ações comuns, como fechar ou cancelar. O GOV.UK pede texto em caixa de frase, que descreve a ação, com verbos claros como continuar, entrar e confirmar. As 2 documentações chegam à mesma ideia: o rótulo diz o que vai acontecer.

Mensagens de erro por tipo de pergunta

A página do componente de opções do GOV.UK traz modelos de mensagem conforme o tipo de pergunta: uma forma para perguntas de sim ou não, outra para 2 opções que não são sim ou não, e outra para mais de 2 opções. Com o modelo na página, a mensagem fica igual em todo o produto.

Texto longo e espaço curto

O Carbon orienta quebrar o rótulo em 2 linhas quando ele não cabe, em vez de cortar o texto com reticências. A regra parece pequena, mas evita botões que escondem a própria ação. Em produtos traduzidos para vários idiomas, ela é decisiva.

Onde fica a regra geral de redação

A regra geral de tom e de vocabulário pertence ao guia de conteúdo da marca. A página do componente traz só o que é específico da peça. O método de escrita para interfaces, em profundidade, está nos artigos de design UX e usabilidade, no hub Desenvolvimento.

Exemplos certos e errados: como mostrar sem confundir

Pares de fazer e não fazer, com conteúdo realista, ensinam mais que qualquer parágrafo, desde que cada par mostre um único erro.

Um erro por par

No Carbon, cada par compara uma decisão: rótulo alinhado à esquerda contra rótulo centralizado, texto quebrado em 2 linhas contra texto cortado, ícone à direita contra ícone à esquerda. Quando um exemplo errado mistura 3 problemas, quem lê não sabe qual deles corrigir.

Conteúdo do próprio produto

Exemplos com texto de preenchimento genérico escondem os problemas reais. Um campo de busca com o rótulo e a dica que o produto usa de fato mostra se o espaço é suficiente. Vale montar os exemplos com o vocabulário da empresa e com dados plausíveis.

Exemplo vivo antes da imagem

Sempre que possível, o exemplo principal deve ser a peça funcionando, com o código ao lado, como faz o GOV.UK no topo da página. A imagem estática mostra a aparência. O exemplo vivo mostra foco, clique e erro.

Pesquisa, problemas conhecidos e histórico

As últimas seções da página registram o que se sabe sobre a peça em uso: pesquisas feitas, limitações conhecidas, mudanças recentes e onde pedir ajuda.

Pesquisa sobre o componente

O GOV.UK mantém em cada página uma seção de pesquisa, que relata testes feitos com a peça e convida outras equipes a compartilhar resultados. Na página do botão, ela registra que botões de início verdes melhoraram a taxa de cliques nos testes do próprio serviço. O registro dá ao componente uma história verificável.

Problemas conhecidos, escritos com franqueza

Na página do componente de opções, o GOV.UK informa que nem sempre o usuário é avisado quando uma pergunta revelada aparece ou some, o que falha no critério 4.1.2 das diretrizes de acessibilidade WCAG 2.2. Declarar a limitação protege quem usa a peça e orienta a próxima versão. A avaliação de acessibilidade em profundidade fica na seção de UX e UI.

Mudanças recentes e canal de ajuda

Uma lista curta das últimas mudanças, com data e versão, diz a quem chega se a página está viva. Um canal de dúvidas no fim da página fecha o ciclo: o que não foi respondido ali vira pergunta registrada e, se se repetir, vira texto novo.

Como saber se a documentação funciona?

A documentação funciona quando as perguntas repetidas diminuem, as cópias locais de componentes param de surgir e as revisões citam a página como critério.

Lista para revisar uma página

  • A primeira frase diz o que a peça resolve
  • Há um exemplo funcionando com o código ao lado
  • A seção de não uso indica a peça alternativa
  • Todos os estados aparecem, inclusive erro e carregamento
  • Cada variação tem papel e regra de combinação
  • Há modelos de texto para rótulos e mensagens
  • Limitações conhecidas estão declaradas
  • A página mostra a data da última mudança

Um teste com quem não participou

Peça a alguém que não desenhou o sistema para montar uma tela só com a documentação. Anote onde a pessoa hesitou e o que perguntou. Cada hesitação aponta uma frase que falta.

O que pedir na entrega da documentação

Peça um modelo de página igual para todos os componentes, com as seções mínimas preenchidas, e um responsável por manter cada página atualizada.

O essencial deste artigo

A página de um componente atende quem desenha e quem programa. Ela traz resumo, exemplo vivo, uso e não uso com alternativa, variações e estados, regras de texto, pesquisa, limitações e histórico. As documentações públicas do GOV.UK e do Carbon mostram ordens diferentes para o mesmo conteúdo. O que importa é manter a mesma ordem em todo o sistema.

O próximo passo

Para começar, abra o briefing na página de design system e diga como os componentes estão descritos hoje. A Trilion é uma agência paulistana, ativa desde 1995 e com escritório em Moema, que atende tanto em reunião presencial quanto por videochamada. Quem pensa a estratégia também desenha e acompanha a aplicação digital. Terminado o briefing, a proposta segue por escrito. Para a parte técnica dos tokens, vale ler o artigo sobre o formato de design tokens do W3C.

Sobre este texto

A Trilion preparou este artigo para o seu hub de Design, e cada fato foi conferido nas páginas listadas abaixo, lidas em 17/11/2026. A estrutura mínima em 8 itens, a lista de estados e o teste com quem não participou são leitura editorial sobre as fontes.

As documentações citadas servem de referência de estrutura. O texto não recomenda copiar o conteúdo delas.

Fontes consultadas

Perguntas frequentes

Qual a seção mais importante da página de um componente?

A de quando não usar, com a peça alternativa indicada. Ela evita o erro mais comum, que é usar a peça certa no lugar errado. Mostrar o componente é fácil; dizer em que situação ele atrapalha é o que transforma a página em orientação.

A documentação de design system serve só para designers?

Não. A página atende quem desenha e quem programa. O primeiro precisa de uso, combinação e texto; o segundo, de propriedades, estados e comportamento. As 2 leituras precisam chegar à mesma conclusão, por isso o exemplo vivo com o código ao lado ajuda tanto.

Quais estados de um componente devem aparecer na documentação?

No mínimo, padrão, foco, ativo, erro e carregando, e o desativado quando existir, com a explicação de por que a peça não está disponível. O estado de foco precisa ser visível para quem navega pelo teclado, e o de erro precisa vir com a mensagem.

Devo declarar limitações conhecidas de um componente?

Sim. Documentações públicas, como a do GOV.UK, registram problemas conhecidos em cada página, inclusive falhas de acessibilidade. A declaração protege quem usa a peça, evita surpresas em produção e orienta a correção na versão seguinte.

Como testar se a documentação está boa?

Peça a alguém que não participou do sistema para montar uma tela usando só a documentação. Anote onde a pessoa hesitou e o que perguntou. Cada hesitação aponta uma frase que falta na página.

Método

Como a Trilion conduz um projeto de interface

Do briefing à entrega dos arquivos finais, em etapas e com tudo por escrito. A proposta vem depois do briefing.

  1. Briefing em 3 passos

    Você conta o momento da marca; nós devolvemos perguntas e um caminho possível.

  2. Diagnóstico e estratégia por escrito

    Telas, fluxos, componentes existentes e marca, levantados antes do desenho.

  3. Desenho em etapas

    Telas e componentes entregues em sistema, prontos para quem programa.

  4. Testes em uso

    A marca aplicada em peças concretas, na tela e no papel, antes de fechar.

  5. Manual e acompanhamento

    Regras registradas, arquivos organizados e a rotina que mantém a marca coerente.

Vamos desenhar a sua interface

Conte o seu projeto. A Trilion responde com uma proposta escrita, depois do briefing, e cuida da estratégia, do desenho e da aplicação.

Falar no WhatsApp
Blog da Trilion · Marketing de luxo

Continue aprendendo sobre marketing de luxo

Artigos do blog da Trilion que aprofundam os temas deste texto. Arraste, use as setas ou o teclado.

WhatsApp
WhatsApp

Converse com a Trilion

Diga-nos o seu nome, e a conversa abre em seguida