ultra11y

ultra11y — auditar RGAA 4.1.2 e escrever código acessível

Em acessibilidade, uma ferramenta automática só vê parte dos problemas. ultra11y assume isso por meio de uma divisão do trabalho: o motor determinístico sem dependências (node scripts/ultra11y.mjs <comando> — sem npm install, sem chave) faz o trabalho mecânico — detectar não conformidades verificáveis por máquina e vinculá-las ao critério RGAA correto; você faz o julgamento — pertinência das alternativas, títulos em contexto, ordem de leitura — e os critérios que exigem uma renderização (contraste, foco, zoom). Portas evitan que qualquer não conformidade alucinada sobreviva.

Regras centrais:

1. Nunca inventar uma não conformidade: cada NC cita um elemento real e resolvível (check o verifica).
2. HTML nativo primeiro, ARIA por último; não duplique uma semântica implícita.
3. O residual é explícito: todo critério de renderização/julgamento não comprovado vai para « a avaliar manualmente », nunca marcado como conforme em silêncio.

Escolher conforme a situação

• « Auditar / relatório de conformidade » → node scripts/ultra11y.mjs audit … --json, depois report, depois check; ler references/audit.md.
• « Em um repositório grande / auditar de forma inteligente » → focar: --changed (diff git), priorização de templates, dedup, --max-files; ler references/scale.md.
• « Implementar as correções » → fix (dry-run por padrão, --write aplica as correções seguras, propõe o restante sem inventar nada); ler references/fix.md.
• « Guarda automática no repositório (hook / CI) » → init --hook/--ci/--baseline (falha apenas em novas não conformidades); ler references/automation.md.
• « Tornar este código acessível / revisá-lo » → auditar o trecho (audit - < componente.html) seguindo o nativo-primeiro; ler references/authoring.md e references/forbidden-patterns.md.
• « O que significa o critério X / qual temática » → criteria; ver references/criteria.md.
• « Leitura internacional (WCAG / EN 301 549 / Section 508) » → --standard wcag em report/criteria; ver references/methodology.md.
• « Auditoria de alta garantia » → verify --report … --semantic; ver references/verify.md. Metodologia e formato: references/methodology.md.
• « Verificar contraste / renderização (tier opcional Docker) » → scan <url> --merge … (axe-core em um navegador headless); ver references/dynamic.md.

Resumo de comandos

node scripts/ultra11y.mjs audit "src/**/*.html" --json > audit.json
node scripts/ultra11y.mjs audit - < componente.html        # HTML via stdin
node scripts/ultra11y.mjs audit "src/**/*.tsx" --jsx       # JSX/TSX melhor esforço
node scripts/ultra11y.mjs audit --changed --json           # apenas o diff git (repositório grande)
node scripts/ultra11y.mjs report --in audit.json --out audits
node scripts/ultra11y.mjs report --in audit.json --standard wcag   # visão WCAG (apresentação)
node scripts/ultra11y.mjs criteria 11.1                    # um critério + seus testes
node scripts/ultra11y.mjs criteria --theme 8 --list        # uma temática / a lista
node scripts/ultra11y.mjs check  --report audits/rgaa-AAAA-MM-JJ.md
node scripts/ultra11y.mjs verify --report audits/rgaa-AAAA-MM-JJ.md --semantic
node scripts/ultra11y.mjs fix "src/**/*.html"              # dry-run ; --write aplica
node scripts/ultra11y.mjs init --hook --baseline           # guarda de regressão (hook + baseline)
node scripts/ultra11y.mjs scan https://exemplo.pt --merge audits/audit-latest.json  # tier Docker

Saída para máquina em todos os lugares com --json. Relatório em francês por padrão, --lang en disponível.

Combinar motor, julgamento e risco residual

A saída audit classifica cada critério: C/NC/NA para o subconjunto estático; manual para os critérios de renderização/julgamento (listados em residualRisks). As NC do motor são candidatos confirmados (citados arquivo:linha). Cabe a você decidir os critérios manual e marcar os critérios de renderização como « a verificar manualmente ». O relatório só está completo quando cada critério aplicável é C/NC/NA justificado e cada risco residual é nomeado.

O que não fazer

• Inventar uma não conformidade que o motor não encontrou e que você não pode ver (o contraste em cores inline literais é resolvido estaticamente; o contraste calculado — CSS externo, variáveis — passa pelo scan (tier Docker) ou se verifica na renderização antes de ser declarado).
• Adicionar ARIA que duplica a semântica nativa.
• Marcar um critério de renderização/julgamento como « conforme » sem verificação humana.
• Editar manualmente references/criteria.md (gerado a partir do referencial).

Escopo

Motor estático: offline, determinístico, sem dependências; entradas HTML + JSX/TSX (melhor esforço) + stdin. Os critérios de renderização (contraste calculado, reflow) são cobertos pelo tier opcional scan (axe-core no Docker); o foco visível, o zoom de texto 200% e os conteúdos ao pairar permanecem em revisão humana (risco residual). Dados: RGAA 4.1.2 © DINUM, Licença Aberta / Etalab 2.0 (ver NOTICE).