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
- Nome da peça e uma frase sobre o que ela resolve.
- Exemplo funcionando, com o código ao lado.
- Quando usar e quando não usar, com a alternativa indicada.
- Variações, cada uma com o papel que cumpre.
- Estados e comportamentos, inclusive os de erro.
- Regras de texto para rótulos, dicas e mensagens.
- Notas de acessibilidade e pesquisa feita com a peça.
- 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.
- GOV.UK Design System, Button: design-system.service.gov.uk
- GOV.UK Design System, Radios: design-system.service.gov.uk
- IBM Carbon Design System, Button usage: carbondesignsystem.com
- Nielsen Norman Group, Therese Fessenden, Design Systems 101: nngroup.com
Fontes consultadas
- GOV.UK Design System: Button (consulta em 17/11/2026)
- GOV.UK Design System: Radios (consulta em 17/11/2026)
- IBM Carbon Design System: Button usage (consulta em 17/11/2026)
- Nielsen Norman Group, Therese Fessenden: Design Systems 101 (consulta em 17/11/2026)

