convez.ai
SkillDesign & UIIntermediário
NikolovG

Auditor de Conformidade de Acessibilidade

NikolovG/ada-compliance-auditor

Audite acessibilidade web contra WCAG 2.1 AA com IA e ferramentas determinísticas

Ver no GitHub
BomPluginScore · de 0 a 100

Skill para Claude que audita páginas web, PDFs, documentos Office, vídeos, áudios e imagens contra padrões WCAG 2.1 Nível AA. Combina ferramentas determinísticas (axe, pa11y) com julgamento de IA para gerar relatórios JSON estruturados e HTML legíveis, cobrindo os 40%+ de problemas que ferramentas automatizadas não detectam.

Instalação

$npx convez-ai NikolovG/ada-compliance-auditor

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
1
Saúde
85%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Auditar conformidade WCAG de sites e aplicações web
  • Verificar acessibilidade de documentos PDF, Word, PowerPoint e Excel
  • Analisar acessibilidade de mídia (vídeos, áudio, imagens) em lote
  • Gerar relatórios de acessibilidade estruturados para conformidade legal

Veredito

Ferramenta sólida e pragmática que preenche lacuna real em testes de acessibilidade: combina automação determinística com IA para cobrir além dos 57% detectáveis por ferramentas sozinhas. Ideal para equipes que precisam validar conformidade WCAG sem queimar recursos em revisão manual. Requer setup inicial de dependências por tipo de mídia, mas compensa em qualidade e escalabilidade de audits.

README

A tradução para o português deste README ainda está na fila.

ada-compliance-auditor

A Claude Skill that audits web pages, PDFs, Office documents, videos, audio files, and images against WCAG 2.1 Level AA. It runs deterministic accessibility tools first, uses Claude only for judgment-heavy checks, and produces a machine-readable JSON report plus a human-readable HTML report.

Start here

1. Install the tools you need

Install only the tool groups for the media types you plan to audit.

For web audits:

npm install -g @axe-core/cli pa11y pa11y-ci accessibility-checker

For PDF audits:

brew install poppler qpdf
# Linux: apt install poppler-utils qpdf
# veraPDF: download from https://verapdf.org and add it to PATH

For video and audio audits:

brew install ffmpeg
# Linux: apt install ffmpeg

For standalone image audits:

brew install tesseract
# Linux: apt install tesseract-ocr
pip install Pillow

For Office document audits:

pip install python-docx python-pptx openpyxl PyYAML
brew install --cask libreoffice

If a tool is missing, the skill records it in audit_metadata.tools_missing and continues with the checks it can still run.

2. Install the skill

For Claude Code:

git clone https://github.com/NikolovG/ada-compliance-auditor.git
mkdir -p ~/.claude/skills
cp -r ada-compliance-auditor/skill ~/.claude/skills/accessibility-audit

For Claude.ai web or desktop with Skills enabled, upload the skill/ folder in the Skills UI.

For a packaged upload:

make package

Then upload dist/accessibility-audit.zip, or upload dist/accessibility-audit/ if your client expects a folder.

3. Run an audit

Ask Claude for an accessibility audit and point it at a URL, file, or directory:

Audit https://example.com for accessibility.
Run an accessibility check on docs/handbook.pdf. We care about WCAG 2.1 AA.
Audit everything in ./public/ as a batch. Use the accessibility-context.yaml at repo root.

Claude should detect the skill, route each subject by media type, run the available tools, and produce audit artifacts.

4. Read the results

Each audit writes to audit-output/<timestamp>/:

  • report.html — readable report for review and triage.
  • report.json — primary EARL-influenced machine-readable report.
  • preflight.json — installed and missing tool status.
  • raw/ and per-subject/ — underlying tool output and per-file reports.

Each finding includes severity, WCAG criterion, source tool, and review_status so you can tell whether it is deterministic, judgment-assisted, human-review-needed, or out of scope.

5. Add project context when needed

For repeat audits, copy skill/assets/example-accessibility-context.yaml into your project as accessibility-context.yaml. Use it to declare target viewports, accepted exceptions, out-of-scope paths, audience notes, and project-specific accessibility constraints.

Why this exists

Accessibility auditing has a tooling gap. The strongest deterministic checkers (axe, pa11y, IBM equal-access) catch around 57% of issues by volume — better than most people assume, far worse than 100%. The remaining 40+% needs human review or LLM judgment, which is where most teams stall: they either drop the report on the floor or burn weeks producing one by hand. The skill is built around that gap. It runs the deterministic tools, structures their output, takes a Claude pass at the things only judgment can decide, and returns a single coherent report that says "here's what we know definitely, here's what needs a human, here's what Claude judged and why, and here's what's out of scope for automation entirely."

It's also opinionated about being practical. Screen sizes aren't universal, design intent matters, and the WCAG standard itself bakes in essential-content carve-outs. The skill respects those carve-outs, supports a per-project accessibility-context.yaml for documenting accepted exceptions, and grades findings on severity (blocker / major / moderate / advisory) so triage queues stay useful instead of becoming a wall of red.

What's in scope

  • Web (HTML/CSS/JS) — strongest deterministic coverage; axe-core primary, pa11y dual-runner secondary, IBM equal-access tertiary for cross-validation.
  • PDF — veraPDF PDF/UA-1 validation, with a pdfinfo tagged-status gate up front so untagged documents fail fast.
  • Office documents — .docx, .pptx, .xlsx via python-docx / python-pptx / openpyxl, with optional LibreOffice→PDF→veraPDF fallback for thorough mode.
  • Video — ffprobe stream metadata for captions and audio descriptions; a luminance heuristic that flags candidates for manual WCAG 2.3.1 (flashing) review.
  • Audio — ffprobe + filesystem sidecar discovery for transcripts under SC 1.2.1.
  • Images (standalone) — tesseract OCR for SC 1.4.5 text-in-image detection, color sampling for contrast signals, SVG metadata inspection.

What's out of scope

  • Native mobile applications (iOS / Android). Native mobile accessibility uses platform-specific tooling (Xcode Accessibility Inspector, Android accessibilityservice) that the deterministic-CLI-first design of this skill doesn't fit. HTML mobile views are in scope — Android/iOS native views are not.
  • Interactive operability checks. Several WCAG criteria (2.1.2 No Keyboard Trap, 2.4.3 Focus Order, 3.2.1 On Focus) require driving the page and observing live focus behavior. The skill flags these as out_of_scope with a checklist for the human tester.
  • WCAG 2.3.1 (Three Flashes) deterministic verdict. PEAT is GUI-only Windows freeware with a proprietary engine and no binary update since 2017; the production commercial standard is HardingFPA. The skill runs a luminance heuristic to flag candidates but does not claim deterministic 2.3.1 coverage. The Trace Center has an open-source replacement in development under NIDILRR grant 90REGE0024 but it's unreleased.
  • Formal conformance claims. The skill produces an audit report. Conformance claims are formal statements that require human attestation. The report includes a conformance_claim_supportable flag that tells the user whether the audit's data so far would support a claim — but never makes the claim itself.

How it's organized

ada-compliance-auditor/
├── skill/                            ← The actual skill. Drop into ~/.claude/skills
│   ├── SKILL.md                      ← Frontmatter + routing logic
│   ├── references/                   ← Reference docs loaded as Claude needs them
│   │   ├── wcag-21-aa.json           ← Canonical: all 50 SCs with tool-coverage flags
│   │   ├── tool-matrix.md            ← Which tool covers which SC
│   │   ├── severity-model.md         ← blocker / major / moderate / advisory framework
│   │   ├── exception-catalog.md      ← WCAG's built-in essential-content carve-outs
│   │   ├── earl-schema.md            ← Output JSON schema
│   │   └── runners/                  ← One detailed procedure per media type
│   │       ├── web.md
│   │       ├── pdf.md
│   │       ├── video.md
│   │       ├── audio.md
│   │       ├── image.md
│   │       └── office.md
│   ├── scripts/                      ← Lightweight orchestration shims
│   │   ├── route.py                  ← MIME-based router
│   │   ├── classify.py               ← Four-bucket review-status + severity
│   │   ├── build_subject_report.py   ← Raw runner output → per-subject JSON
│   │   ├── merge_reports.py          ← Per-subject reports → final EARL JSON
│   │   ├── render_report.py          ← JSON → HTML view
│   │   └── run_<media>.{sh,py}       ← Per-media-type tool wrappers
│   └── assets/
│       ├── example-accessibility-context.yaml
│       └── report-template.html
├── scripts/
│   └── package_skill.py              ← Builds a correctly named skill package
├── evals/
│   └── evals.json                    ← Test prompts for the skill-creator loop
├── samples/                          ← Tiny fixtures for the eval suite
├── BLUEPRINT.md                      ← Design decisions and reasoning
├── CONTRIBUTING.md
├── LICENSE                           ← MIT
└── README.md                         ← You are here

Output

Each run produces:

  • A JSON report (EARL-influenced, using the ACT Rules @context) — the primary, machine-readable output. Full schema in skill/references/earl-schema.md.
  • An HTML report rendered from the JSON, for humans.
  • A chat summary highlighting the top blockers and majors and pointing at the saved reports.

Each finding carries:

  • The WCAG success criterion it relates to (e.g., 1.4.3, level AA).
  • A severity — blocker / major / moderate / advisory, capped per the rules in severity-model.md and adjusted for context.
  • A review_status — definite (tool said so), needs_human_review (tool couldn't decide), llm_judged (Claude reasoned about it; rationale attached), or out_of_scope (architectural limit; checklist attached).
  • The tool and rule_id that produced the finding, so consumers can trace back.
  • An exception_eligible flag for criteria with built-in essential-content exceptions, and an exception_claimed flag for findings the user's context file has documented as accepted.

Maturity and limitations

This repository is suitable for public use as a v0.x skill: the core routing, preflight, report rendering, web normalization, PDF tagged-status gate, Office signal collection, and image signal collection are implemented and covered by tests. It is still intentionally conservative. Several quality checks remain judgment-assisted (llm_judged) or human-review-only (out_of_scope) because the available deterministic tools cannot decide them reliably.

The most important gaps are documented in BLUEPRINT.md. High-value follow-up work includes authenticated-page support, LLM-backed eval automation, larger fixture corpora with ground truth, and parser coverage for additional raw outputs from veraPDF, video, audio, image, and Office runners.

Legal context

WCAG 2.1 AA is the practical floor for ADA compliance in the U.S. as of 2026. The DOJ's April 2024 final rule for Title II of the ADA requires state and local government web content and mobile apps to meet WCAG 2.1 AA. An April 2026 interim final rule extended compliance deadlines to April 2027 (large entities) and April 2028 (smaller entities). Title III (private entities open to the public) has no federal rule but ample case law treating WCAG 2.1 AA as the de facto standard.

The EU's EN 301 549 references WCAG 2.1 AA. Section 508 (federal procurement) references WCAG 2.0 AA but most procurement contracts now require 2.1.

This skill targets WCAG 2.1 AA by default. Other levels and WCAG 2.2 AA are configurable via conformance_target in accessibility-context.yaml.

What this is not

  • A lawyer. This skill produces technical reports, not legal advice. ADA compliance is contextual and depends on the specific entity, content, audiences, and jurisdictions involved. Consult an accessibility lawyer for binding guidance.
  • A magic 100% audit. Automated tooling catches roughly 30–60% of real-world accessibility issues. The skill is honest about that — every report distinguishes what the tools decided from what needs human verification.
  • A replacement for testing with real assistive technology. Findings around keyboard operability, screen-reader pronunciation, magnifier behavior, and voice-control accuracy require testing with actual NVDA / JAWS / VoiceOver / TalkBack / Dragon / etc. The skill flags these as out_of_scope with checklists.

License

MIT. Tool dependencies have their own licenses — most permissive (MIT/Apache/MPL), but a few are LGPL or GPL invoked as separate processes (poppler, ffmpeg). See BLUEPRINT.md for the license breakdown.

Contributing

See CONTRIBUTING.md. The highest-value contributions right now are:

  1. Real-world test corpora (HTML/PDF/Office docs with known accessibility issues + ground truth).
  2. Refinements to the per-runner reference docs based on tool-version drift.
  3. New eval prompts that exercise edge cases.
Ver o original no GitHub

Bom para

Relacionados