Acessibilidade
Mantenha cada página utilizável com um leitor de tela: títulos e links descritivos, sem linguagem direcional, alt text e instruções explícitas.
Alguns leitores usam um leitor de tela, alguns navegam pelo teclado e alguns não distinguem cores. As regras desta página mantêm a documentação utilizável para todos eles. Elas seguem as Web Content Accessibility Guidelines (WCAG) 2.2.
Escreva um título de página descritivo e único
O título identifica a página nos resultados de busca, na aba do navegador e no anúncio de página do leitor de tela. Um título genérico não identifica nada, e duas páginas com o mesmo título ficam indistinguíveis. Coloque a informação mais específica primeiro e nunca repita um título.
- Incorreto:
Solução de problemas - Correto:
Solucione erros de resolução de DNS
Use um único H1 e não pule níveis de heading
Um usuário de leitor de tela navega de heading em heading, e o esquema de headings funciona como o sumário da página. O campo title do frontmatter vira o único H1 da página. Comece o corpo em ## e avance um nível por vez. Um salto de ## para #### implica um nível que não existe, e o esquema perde a estrutura.
As regras completas de headings estão em Títulos.
Escreva textos de link que nomeiam o destino
Um leitor de tela pode apresentar os links de uma página como uma lista, fora das frases. Nessa lista, “clique aqui” e “leia mais” não nomeiam nada, e cada link genérico soa igual aos outros. Use o título da página de destino como texto do link.
- Incorreto:
Para os limites de comprimento, [clique aqui](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/). - Correto:
Os limites de comprimento estão em [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/).
As regras de formatação de links estão em Formatação de texto.
Não use linguagem direcional
”A caixa à direita” e “a seção abaixo” descrevem uma posição. A posição muda com o tamanho da tela e não significa nada para um leitor de tela, que lê a página em uma única ordem. Nomeie o elemento ou a seção.
- Incorreto:
Clique no botão abaixo. - Correto:
Selecione **Save**. - Incorreto:
Veja a seção acima. - Correto:
Consulte a seção Pré-requisitos.
Escreva texto alternativo que descreve o que a imagem transmite
O texto alternativo (alt text) substitui a imagem para o usuário de leitor de tela. Descreva o que a imagem transmite e por que ela está na página, em menos de 150 caracteres. Para um diagrama complexo, coloque a descrição completa no texto ao redor da imagem e mantenha o texto alternativo curto.
Não comece com “imagem de” ou “foto de”: o leitor de tela já anuncia o elemento como imagem. Use texto alternativo vazio (![]) apenas para uma imagem puramente decorativa. Não acumule keywords, porque o texto alternativo serve ao leitor, não ao ranking de busca.
- Incorreto:
 - Incorreto:
 - Correto:
Não use apenas cor em diagramas
A cor não chega a todo leitor: muitos leitores não a distinguem, e um leitor de tela não a anuncia. Em um diagrama, use rótulos ou formas além da cor, e escreva a legenda com nomes, não com cores.
- Incorreto:
As caixas verdes são as respostas em cache. - Correto:
As caixas com o rótulo "cache hit" são as respostas em cache.
Expanda as siglas no primeiro uso
Escreva cada sigla por extenso no primeiro uso em cada página, porque o leitor chega a qualquer página diretamente. A regra completa está em Escolha de palavras.
Escreva instruções explícitas
Uma instrução nomeia o controle e a ação, porque “salve as alterações” deixa o leitor procurar o controle na tela. Quando um campo tem um formato ou um limite, inclua a exigência no próprio passo.
- Incorreto:
Salve as alterações. - Correto:
Selecione **Save**. - Incorreto:
Insira um valor. - Correto:
Insira o TTL em segundos.