Que problema estamos resolvendo?

Uma equipe pode lembrar de títulos, texto alternativo e contraste, mas esquecer que exemplos também são conteúdo. A página parece boa, mas o trecho mais importante — um exemplo de código, uma resposta JSON ou uma tabela — pode ser difícil de ler, depender demais de cor ou ser ruim para leitores de tela.

Uma boa orientação não apenas recomenda cuidado: ela mostra o padrão correto dentro do próprio artigo com contexto, resultado esperado, estrutura visível e texto que continua funcionando mesmo sem cor.

Princípios para exemplos acessíveis

  1. Explique o objetivo antes do bloco.
  2. Não use cor como único portador de significado.
  3. Separe sucesso, aviso e erro.
  4. Use tabela apenas para relações realmente tabulares.
  5. Mantenha um fato por célula e um propósito por exemplo.

Exemplo 1. Explique a tarefa e depois mostre a requisição

Obtenha o relatório 42. Substitua <token> por um token válido. Em caso de sucesso, o servidor retorna HTTP 200 e um JSON em que status é ready.

GET /v1/reports/42 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
{
  "id": 42,
  "status": "ready",
  "download_url": "/v1/reports/42/file"
}
{
  "error": "not_found",
  "message": "O relatório 42 não existe ou não está mais disponível."
}

Exemplo 2. O cabeçalho da tabela deve carregar o significado

Campo Tipo Obrigatório Significado Observação
id integer sim Identificador do relatório Presente em todas as respostas de sucesso
status string sim Estado do processamento Valores típicos: queued, running, ready, failed
download_url string não Link para o arquivo Só aparece quando status é ready
error string não Código de erro Apenas em respostas com falha
Verificação Pergunta Bom sinal
Objetivo O propósito do exemplo está claro? O leitor antecipa o resultado
Estrutura Sucesso e erro estão separados? Há blocos ou rótulos distintos
Tabela Os cabeçalhos definem o significado? A célula faz sentido com o cabeçalho
Linguagem A explicação é clara e curta? O texto ajuda o exemplo

Exemplo 3. Quando a estrutura importa, mostre o markup

<table>
  <caption>Campos da resposta do relatório</caption>
  <thead>
    <tr>
      <th scope="col">Campo</th>
      <th scope="col">Tipo</th>
      <th scope="col">Obrigatório</th>
      <th scope="col">Significado</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><code>status</code></th>
      <td>string</td>
      <td>sim</td>
      <td>Estado atual do processamento</td>
    </tr>
  </tbody>
</table>

O que evitar

  • bloco de código sem contexto;
  • sucesso ou erro indicados apenas por cor;
  • uso de tabelas para passos ou parágrafos longos;
  • muitas informações independentes na mesma célula;
  • capturas de tela de código em vez de texto copiável.

Padrão prático para autores

  1. Objetivo.
  2. Pré-requisito.
  3. Exemplo.
  4. Resultado esperado.
  5. Erro comum.
  6. Tabela de referência, se necessário.

Checklist editorial curto

  • Explique o propósito antes do bloco.
  • Separe sucesso e erro.
  • Torne o código compreensível sem cor.
  • Use tabela apenas quando houver relação real entre linhas e colunas.
  • Prefira texto copiável a imagens de código.

Materiais relacionados