Report Generation
Report File
Default output: DOCUMENT-ACCESSIBILITY-AUDIT.md in the project root.
Required Sections
Every audit report MUST include these sections:
- Audit Information - date, auditor, profile, scope, counts
- Executive Summary - totals, pass rate, most common issue, effort estimate
- Cross-Document Patterns - recurring issues, systemic failures
- Findings by File - per-document issues with rule ID, severity, location, WCAG, impact, remediation
- Findings by Rule (Cross-Reference) - rule-level aggregation across files
- What Passed - acknowledge clean documents and categories
- Remediation Priority - ordered by impact (Immediate / Soon / When Possible)
- Accessibility Scorecard - per-document scores and grades
- Metadata Dashboard - document properties health
- Confidence Summary - breakdown by confidence level
Optional Sections (include when applicable)
- Template Analysis - when batch scanning detects shared templates
- Comparison Report - when re-scanning against a baseline
- CI/CD Recommendations - when no config files exist
Severity Scoring Formula
The score and grade in a rendered report come from
skills/a11y-core/scripts/merge-findings.mjs (weights critical 10, serious 5,
moderate 2, minor 1; confidence high 1.0, medium 0.7, low 0.4; grades A 90+,
B 80+, C 70+, D 60+, F below). The formula is in kb-web-severity-scoring.
Map a document checker's levels onto the canonical severities first
(kb-severity-mapping) rather than scoring errors and warnings directly.
Score Grades
Each score band, with its grade and meaning.
| Score | Grade | Meaning |
|---|---|---|
| 90-100 | A | Excellent - few barriers found |
| 80-89 | B | Good - some barriers found |
| 70-79 | C | Needs Work - many barriers remain |
| 60-69 | D | Poor - significant barriers |
| 0-59 | F | Failing - unusable with AT |
Organization Modes
Each mode, with description and best for.
| Mode | Description | Best For |
|---|---|---|
| By file | Group all issues under each document | Small batches (< 10 files) |
| By issue type | Group all instances of each rule across documents | Seeing patterns |
| By severity | Critical first, then serious, moderate, minor | Prioritizing fixes |
VPAT/ACR Compliance Export
Conformance Levels
Each level, with its criteria.
| Level | Criteria |
|---|---|
| Supports | No findings for this WCAG criterion across any document |
| Partially Supports | Some documents pass, some fail |
| Does Not Support | All or most documents fail |
| Not Applicable | Criterion does not apply to scanned document types |
Supported VPAT Editions
The current ITI template is VPAT 2.5Rev (24 April 2025), as of October 2026.
- VPAT 2.5 (WCAG) - maps to WCAG 2.0, 2.1 and 2.2 criteria
- VPAT 2.5 (508) - maps to Revised Section 508 standards (WCAG 2.0 AA)
- VPAT 2.5 (EU) - maps to EN 301 549; the template still points at V3.2.1 (WCAG 2.1 AA)
- VPAT 2.5 (INT) - International edition (all three combined)
4.1.1 Parsing is obsolete in WCAG 2.2 and is never reported as a 2.2 failure.
For the 4.1.1 rows that 2.0 and 2.1 based tables still carry, follow
skills/kb-legal-compliance-mapping/SKILL.md. Date every ACR and say which
edition and standard versions it covers.
Remediation Tracking
When comparing against a baseline audit report:
| Status | Meaning |
|---|---|
| Fixed | Issue was in previous report but is now resolved |
| New | Issue was not in previous report but appears now |
| Persistent | Issue remains from previous report |
| Regressed | Issue was previously fixed but has returned |
Progress Metrics
- Issue reduction percentage:
(fixed / previous_total) * 100 - Score change:
current_score - previous_score - Documents improved: count of documents with higher scores