# Acessibilidade

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](/pt-br/documentacao/guia-de-estilo/formatacao/titulos/).

## 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](/pt-br/documentacao/guia-de-estilo/formatacao/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: `![Screenshot](/assets/docs/images/uploads/request-flow.png)`
- Incorreto: `![edge, cache, CDN, fluxo de requisição, cache](/assets/docs/images/uploads/request-flow.png)`
- Correto: `![Diagrama de uma requisição que vai do cliente, pela infraestrutura distribuída da Azion, até a origem](/assets/docs/images/uploads/request-flow.png)`

## 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](/pt-br/documentacao/guia-de-estilo/escrita/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.`