SocialGouv/ultra11y

ultra11y — audita WCAG 2.2 AA e escreva marcação acessível

Em acessibilidade, uma ferramenta automatizada vê apenas parte do problema. O ultra11y lida com isso através de uma divisão de trabalho: o mecanismo determinístico, sem instalação (node scripts/ultra11y.mjs <comando> — sem npm install, sem chave; o analisador JSX/TSX embutido no pacote) faz o trabalho mecânico — detecta as não conformidades verificáveis por máquina e as associa ao critério de sucesso WCAG correto — enquanto o agente de codificação ativo julga os próprios critérios de julgamento — relevância de texto alternativo, propósito do link no contexto, ordem de leitura — estaticamente, a partir das evidências coletadas pelo mecanismo (verify --manual), cada veredito protegido por portões verify/check. Apenas os critérios verdadeiramente baseados no DOM renderizado (contraste calculado, foco visível, zoom/reflow, conteúdo ao passar o mouse) ficam a cargo da camada scan (axe-core em um navegador real); um humano é, no máximo, uma supervisão opcional. Os portões impedem que qualquer não conformidade alucinada sobreviva, e nada é silenciosamente considerado "conforme".

Não confunda regras com critérios. O pacote inclui 93 verificações estáticas, a WCAG AA tem 55 critérios de sucesso e a RGAA tem 106 critérios. Várias regras podem evidenciar um critério, uma regra pode contribuir para vários critérios do pacote, e a maioria dos critérios permanece aberta até uma varredura ou um julgamento. A única cobertura honesta em nível de execução é a contagem de proveniência ao vivo da grade (moteur + scan + agent, mais qualquer resíduo indecidível nomeado), nunca uma promessa fixa como “48 critérios do agente”. Os resumos do GitHub mostram, portanto, decidido/total, não uma porcentagem sobre o pequeno subconjunto decidido.

WCAG 2.2 Nível AA é o núcleo mundial. Padrões nacionais — RGAA da França, Seção 508 dos EUA, EN 301 549 da UE — são pacotes de padrões plugáveis que mapeiam seus critérios para a WCAG. Adicione --standard rgaa para redefinir cada comando e cada saída — audit inclusive, resultados e tudo mais; plugue um pacote externo em tempo de execução com --pack ./pack.json (ou um .ultra11yrc.json), sem reconstrução; ou contribua com seu país (veja references/standards.md). Pacotes (e suas diretrizes de implementação concretas — os padrões bons/ruins do SocialGouv/etalab para RGAA) podem ser ingeridos por IA e protegidos por pack check para que um mapeamento fabricado jamais passe — veja references/packs.md e references/guidance.md.

A maior parte do trabalho é sua. Dos 55 critérios de sucesso da WCAG 2.2 AA, o mecanismo pode decidir 3 diretamente; 14 precisam de uma página renderizada (scan) e 38 são chamadas de julgamento que o agente decide. Portanto, a execução limpa do mecanismo é um ponto de partida, nunca um veredito — e references/adjudication.md é a página a partir da qual você realmente trabalha.

Regras principais:

1. Nunca invente uma não conformidade: cada NC cita um elemento real e resolvível (check o verifica).
2. HTML nativo primeiro, ARIA por último; nunca duplique semânticas implícitas.
3. Nunca invente uma conformidade também: um C é citado exatamente como um NC — ele nomeia em citations[] a evidência coletada que foi aprovada, cada âncora resolvível e extraída da evidência que aquele critério realmente mostrou. Um critério apresentado sem evidência não pode ser C; ele permanece manual. Tampouco pode aquele cuja leitura foi INCOMPLETA (evidenceComplete: false): um critério do qual você viu parte ainda pode falhar no que você viu, mas nunca pode ser aprovado sobre o que você não viu. E um C julgado nunca é mesclado com um decidido pelo mecanismo: os relatórios o listam separadamente e o mantêm fora da taxa de aprovação automática. 3b. O que é mostrado a você é a população inteira, dita uma vez por coisa distinta. A evidência é um representante por CLASSE DE CONTEÚDO, carregando occurrences, as outras âncoras em alsoAt, e as pages em que aparece — 887 links em 38 páginas capturadas são 97 pares (texto, href) distintos. Julgar o representante julga todos eles, e é isso que torna um C honesto alcançável; e uma citação nomeando qualquer ocorrência de uma classe que o critério carrega é aceita, então cite aquela que você realmente abriu.
4. O residual é explícito, nunca silenciosamente conforme: o agente de IA julga cada critério de julgamento ele mesmo (verify --manual, com portão), e os critérios de renderização vão para scan — que agora CONCLUI C (decidedBy: "scan") quando cada regra que carrega um critério foi executada em todas as páginas do escopo e não levantou nada, e permanece em silêncio quando mesmo uma página tem sinais incompletos. Qualquer critério ainda não comprovado permanece "para avaliar manualmente" — nenhum status sem um veredito registrado e justificado. Para tornar isso um portão em vez de uma esperança, check --in <audit.json> --require-decided falha enquanto algo ainda estiver para avaliar, e --allow-undecided <file> aceita os critérios que você genuinamente não pode decidir, cada um com sua razão (uma lista nomeada, nunca um limite). --require-decided=pages mantém a própria grade de CADA página no mesmo padrão: um critério que falha em uma rota é resolvido para a execução e pode ainda não ser o veredito de ninguém nas rotas em que nunca disparou, que é como um entregável por página é realmente julgado. A lista de trabalho emitida é autoritativa. Ela pode conter deliberadamente um critério cujo status geral da execução já é NC, porque essa falha não decidiu o critério nas outras páginas. Tal item não é redundante: retorne um veredito fundamentado para ele (ou uma razão manual explícita), nunca o deixe em branco porque o total global parece decidido.
5. Consulte o critério; nunca o recite de memória. criteria [--standard <pack>] <id> — ou ultra11y_criteria via MCP — retorna a própria redação do critério, seus testes numerados, e as definições de glossário que esses testes citam. RGAA 8.3 não é "a página precisa de um atributo lang"; é o teste 8.3.1 com duas condições alternativas, e o glossário decide o que seus termos significam. Um bloco de auditor que cita 8.3.1 após lê-lo é fundamentado; aquele que o cita de memória é um palpite vestido de referência. Antes de auditar contra um padrão nacional, execute o plano (ultra11y_method): ele informa quantos de seus critérios ainda precisam de julgamento para ganhar C — para RGAA, 104 de 106. Veja references/mcp.md.
6. O HTML semântico renderizado FINAL deve estar correto. O mecanismo vê apenas o código fonte; uma biblioteca de componentes (DSFR/MUI…) ou SFC .vue/.svelte/.astro oculta a marcação real, portanto uma auditoria verde do código fonte não é prova. Verifique o HTML semântico produzido — instale o coletor capture de toque zero (render --setup) para que cada componente que seus testes renderizam seja serializado em .ultra11y/captures e auditado, com audit --require-captures protegendo os pontos cegos. Veja references/automation.md / rendered.md.
7. Idioma: SEMPRE passe --lang correspondendo ao idioma da sua conversa com o usuário; pergunte ao usuário quando ambíguo. Sem a flag, a CLI detecta automaticamente (repo <html lang> → a localidade padrão do padrão ativo → Inglês) — uma alternativa para scripts/CI, não um substituto para passar --lang você mesmo.
8. Tokens técnicos permanecem em inglês, mesmo em prosa francesa. Em qualquer entrega em francês que você escrever (comentário de relatório, PRD, tickets do rastreador, vereditos de julgamento), nomes de atributos/elementos/papéis e seus valores são código, não prosa — nunca os traduza: aria-live permanece aria-live (nunca « région live »), o mesmo para tabindex, alt, role="alert", nomes de papéis de referência. O próprio catálogo em francês do mecanismo segue isso; corresponda a ele. Vocabulário normativo de padrões (redação RGAA como « lien d'évitement ») mantém seu francês oficial.

A biblioteca de referência

Conhecimento de domínio primeiro, depois a ferramenta. Leia aquele que corresponde à pergunta à sua frente.

Conhecimento de acessibilidade
references/adjudication.md	Como decidir cada um dos 52 critérios que o mecanismo lhe entrega — a regra de decisão, quando NA é legítimo, as perguntas
references/naming.md	Cálculo do nome acessível, 2.5.3 label-in-name, CSS visualmente oculto, nomeação de imagens/SVG/figuras
references/widgets.md	Padrões compostos ARIA APG, contratos de teclado, gerenciamento de foco, mudanças de rota SPA, regiões ativas
references/forms-and-errors.md	Rótulos e instruções, a lista de tokens autocomplete, identificação/sugestão/prevenção de erros, entrada redundante, autenticação acessível
references/structure.md	Cabeçalhos, referências, listas e dl, tabelas simples e complexas, sequência significativa
references/media-and-motion.md	Legendas/descrição de áudio/transcrições, gestos de ponteiro, tamanho do alvo, orientação, reflow, movimento reduzido
references/forbidden-patterns.md	15 antipadrões: ruim → por quê → correção nativa → critério
references/focus-and-logic.md	Os critérios de foco/teclado que você possui, e como raciocinar sobre eles
references/criteria.md	Os 55 critérios: nível, classe de automatização, regras do mecanismo, mapeamento de pacotes (gerado)
references/rgaa-automation.md	RGAA 4.1.2: matriz gerada de 106 critérios / 258 testes, regras decisivas, sinais candidatos e política de silêncio
references/act.md	O que o mecanismo é medido para capturar — e o que ele demonstradamente não captura (gerado)

Executando a ferramenta
references/runbook.md	A execução confiável: a única receita, o transporte a usar e por quê, e quanto custa uma passada. Leia isto antes de pagar por um julgamento
references/claude-code-report.md	A rota de publicação detalhada do Claude Code: escopo renderizado, julgamento direto, verificação adversarial, Markdown + HTML + evidência por página
references/audit.md	O loop de auditoria de ponta a ponta, e a amostra de página normativa
references/judgment.md	As listas de trabalho de julgamento + refutação, vocabulário de veredito, dobra de fechamento de falha
references/verify.md	Os portões check/verify
references/false-positives.md	Onde uma descoberta ainda pode estar errada, e como refutá-la
references/rendered.md · references/automation.md	Auditando HTML produzido, capturas, hooks e CI
references/harnesses.md	Onde isso é executado: Claude Code, Codex CLI, OpenCode, e a alternativa AGENTS.md
references/orchestrators.md	Conduzindo o mecanismo a partir de um motor de fluxo de trabalho / CI não-GitHub: fixação, pipeline de seis etapas, códigos de saída, o conjunto de tickets como JSON para qualquer rastreador
references/ci.md	`--format sarif
references/pages.md	Instantâneos de página + a grade de critérios por página (pages), e suas regras de honestidade
references/e2e.md	render --e2e: auditando uma página durante sua execução do Playwright/Cypress
references/devtools.md	dev: a sobreposição ao vivo enquanto você constrói, e o painel por página
references/extension.md	A extensão do navegador: audite a página que você está vendo, através do side-car
references/dynamic.md	A camada scan: tempos de execução, sondas, páginas autenticadas
references/scale.md	Focando uma auditoria em um repositório grande
references/fix.md · references/correction.md	Aplicando correções, por prioridade, sem regressões
references/prd.md	O bloco de auditor como um backlog (markdown)
references/tickets.md	Registrando esse backlog como tickets: GitHub, GitLab, Jira, e em qual granularidade
references/standards.md · references/packs.md · references/guidance.md	Padrões nacionais, criando um pacote, diretrizes de implementação
references/mcp.md	Os padrões como um motor de regras: consulte um critério em vez de recitá-lo de memória — seus testes numerados, os termos que define, a correção e o plano de trabalho. Como ferramentas MCP e recursos std://, ou os mesmos dados na CLI
references/methodology.md	Status, taxa de aprovação, severidades, formato do relatório
references/cross-file.md	--graph: imports e regras entre arquivos
references/orchestration.md	Distribuindo as fases de julgamento entre subagentes

Escolha por situação

• "Produzir uma auditoria/relatório detalhado no Claude Code" → use a sessão ativa do Claude como o auditor, feche os critérios renderizados e de julgamento, desafie suas alegações, depois publique o relatório datado em Markdown, HTML imprimível e dossiês por página com evidências. Leia references/claude-code-report.md. Este é o perfil de publicação interativo; termine com seu conjunto completo de entregáveis. O resumo compacto é a branch de CI abaixo.
• "Auditoria / relatório de conformidade" → node scripts/ultra11y.mjs audit … --json, depois report (tabela de síntese + um bloco de conformidade do auditor por critério NC — o mesmo bloco usado por prd e tickets), depois check; leia references/audit.md.
• "Código renderizado por uma biblioteca (DSFR, MUI…) ou um SFC .vue/.svelte/.astro / evitar falsos negativos" → audite o HTML produzido, não o template fonte. Mais fácil: instale o coletor capture de toque zero (render --setup) para que seus testes serializem cada componente renderizado para .ultra11y/captures (ingerido automaticamente, descobertas atribuídas ao componente fonte; render --coverage e audit --require-captures rastreiam pontos cegos). Ou render (receita build→auditoria ou snapshot SSR --scaffold) depois audit na saída, e scan para renderização calculada. Descobertas de código-fonte SFC são sinalizadas como preliminary (uma ressalva scope.sourceTemplate); leia references/rendered.md.
• "Uma descoberta parece errada / falso positivo em um componente" → o mecanismo suprime automaticamente a maioria dos falsos positivos de componentes (nomes injetados por slot/prop, filhos de componente, ligações dinâmicas, cabeçalhos condicionais) e marca descobertas de fonte SFC/biblioteca como preliminary; confirme ou refute o restante com verify --apply; leia references/false-positives.md.
• "Repositório grande / auditar de forma inteligente" → foque: --changed (git diff), priorização de template, dedup, --max-files; leia references/scale.md.
• "Análise entre arquivos (árvore + dependências), JSX/TSX como AST real" → audit --graph resolve imports e aplica regras entre arquivos

…

[truncado para tradução]