🗺️ O Fluxo de Consumo de Documentação Acessível

flowchart TD
    MD["Arquivo Markdown Bem Estruturado"]
    --> PARSER["Conversor para HTML5 Semântico"]
    
    PARSER --> AT["Tecnologias Assistivas (Leitores de Tela NVDA / JAWS / VoiceOver)"]
    PARSER --> BROWSER["Navegadores Convencionais"]
    
    AT --> H1["Árvore de Cabeçalhos Linear (H1 -> H2 -> H3 sem saltos)"]
    AT --> ALT["Textos Alternativos Descritivos para Imagens e Diagramas"]
    AT --> TABLE["Cabeçalhos de Tabela com Escopo Adequado"]

    style MD fill:#ede7f6,stroke:#512da8,stroke-width:2px
    style PARSER fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    style AT fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style BROWSER fill:#e1f5fe,stroke:#03a9f4,stroke-width:1.5px
    style H1 fill:#00897b,stroke:#004d40,stroke-width:1.5px,color:#ffffff
    style ALT fill:#00897b,stroke:#004d40,stroke-width:1.5px,color:#ffffff
    style TABLE fill:#00897b,stroke:#004d40,stroke-width:1.5px,color:#ffffff

📖 Fundamentos e Aplicação

Escrever documentação técnica não se resume à sintaxe: é fundamental garantir que desenvolvedores com deficiência visual, motora ou neurodivergências consigam navegar e compreender o conteúdo. O padrão WCAG (Web Content Accessibility Guidelines) aplica-se diretamente ao HTML gerado a partir do seu Markdown.

Pilares de Acessibilidade em Markdown:

  1. Hierarquia Rigorosa de Cabeçalhos: Nunca pule níveis (ex.: nunca pule de # H1 diretamente para ### H3 apenas por razões estéticas). Leitores de tela utilizam a árvore de headers como índice de navegação rápida.
  2. Textos Alternativos Significativos (alt text):
    • ❌ Ruim: ![imagem](arquitetura.png) ou ![diagrama](diagrama.png)
    • ✅ Bom: ![Diagrama de blocos mostrando o fluxo de requisição do gateway para o microsserviço de autenticação](arquitetura.png)
  3. Links com Contexto Explícito:
    • ❌ Ruim: Para baixar a CLI, clique [aqui](...).
    • ✅ Bom: [Baixar a CLI do Antigravity para Windows e Linux](...).