A well-documented accessibility issue includes seven things: the WCAG success criterion it maps to, the page or screen where it appears, a clear description of the problem, a code snippet or screenshot, the user impact, a severity rating, and a recommended fix. Each issue should be self-contained, so a developer can read one row and act on it without needing to ask follow-up questions. The report itself organizes these issues in a structured format, typically a spreadsheet or live document, with consistent columns and filters. Auditors at Accessible.org document this way on every project.
| Field | What it captures |
|---|---|
| WCAG criterion | The specific success criterion (e.g., 1.4.3 Contrast Minimum) the issue maps to |
| Location | Page URL, screen name, or component reference |
| Description | Plain-language explanation of the issue and where it appears in the interface |
| Evidence | Screenshot, code snippet, or both, with the problem area marked |
| User impact | How the issue affects users of assistive technology or with specific disabilities |
| Severity | Critical, high, medium, or low, based on a defined rubric |
| Recommendation | The fix, written so a developer can act on it without further input |
What does a documented accessibility issue actually look like?
Take a button on a checkout page with a label that reads “Click for more” and no programmatic name beyond that text. The issue row in the report would list WCAG 2.4.6 Headings and Labels and 2.5.3 Label in Name. The location would be the checkout URL with the button selector. The description would explain that the visible label does not match the accessible name announced by screen readers.
Evidence would include a screenshot of the button and the relevant HTML. User impact: screen reader users hear a name that does not match what they see, which breaks voice control commands. Severity: high. Recommendation: update the accessible name to match the visible text, or revise the visible text to describe the action.
That single row gives a developer everything they need. No back-and-forth. No guessing.
How should the report be structured?
The most useful format is a spreadsheet or a live document where each row is one issue and each column is one field. Filters let teams sort by severity, page, or WCAG criterion. This is the format Accessible.org uses for every audit report delivered to clients.
Avoid PDF-only reports when possible. PDFs are fine as a snapshot, but a working spreadsheet lets developers update status, assign owners, and track progress as remediation moves forward. The report becomes a project management artifact, not a static document.
Group issues by page or by component, depending on the asset. For a marketing website, by page works. For a web app or mobile app, by screen or component is usually cleaner.
How do you describe an issue clearly?
Write descriptions in plain language. Assume the reader is a developer who knows their codebase but may not know WCAG by heart. State what the problem is, where it appears, and what assistive technology behavior confirms it.
A weak description: “Form has accessibility issues.” A strong description: “The email input on the contact form has no associated label element. Screen readers announce the field as ‘edit text’ with no context.”
Specificity is the point. Vague issue descriptions create rework. Precise descriptions move straight into a developer’s queue.
How do you assign severity?
Severity should follow a defined rubric so ratings stay consistent across the report. A common four-level rubric:
Critical: Blocks a user from completing a core task (e.g., checkout, sign-up, form submission). High: Significantly degrades the experience but a workaround exists. Medium: Noticeable issue that affects usability without blocking tasks. Low: Minor issue with limited user impact.
Severity is separate from WCAG level. A Level A criterion can produce a low-severity finding in one context and a critical one in another. The rubric reflects user impact, not the criterion’s classification.
From there, teams can apply Risk Factor or User Impact prioritization formulas to decide what to address first. The audit report identifies the issues. Prioritization decides the order.
What evidence should be included?
Screenshots with the problem area highlighted, plus the relevant HTML or component code. For dynamic states (focus, hover, error), capture the state in question, not the default view.
For mobile apps, include the screen name and the assistive technology used to confirm the issue (VoiceOver on iOS, TalkBack on Android). For documents (PDFs, presentations), include the file name and page or slide number.
Video clips help for issues that involve motion, focus order, or keyboard navigation. A 10-second screen recording often communicates more than a paragraph of description.
What about scans?
Scans flag approximately 25% of issues and cannot determine WCAG conformance. They are useful for catching certain issues quickly, but their output is not a substitute for a documented audit report. A scan tells you something might be wrong. A manual evaluation confirms what is wrong, why it matters, and how to fix it.
If a report is built from scan output alone, it will miss most of what users actually encounter. The two activities serve different purposes and should not be combined into one document.
FAQ
Who should write the accessibility issue report?
A qualified auditor with hands-on knowledge of WCAG and assistive technology. Internal teams can document issues they discover, but a full audit report should come from an auditor who has evaluated the asset end to end. Accessible.org auditors produce reports that map directly to WCAG 2.1 AA or 2.2 AA criteria with severity, evidence, and recommendations on every row.
How long should an accessibility issue report be?
Length depends on the asset. A small marketing site might produce 30 to 60 issues. A web app with dozens of screens can produce several hundred. The point is not the count. The point is that every issue is documented thoroughly enough that a developer can act on it without follow-up.
Can AI help generate the report?
AI can help draft descriptions, summarize patterns, and surface recommendations once issues are identified, which makes the documentation work more efficient. AI cannot identify all the issues itself. Accessible.org Labs is actively researching how AI can support auditors and developers in the documentation and remediation workflow, with the practitioner staying at the center of the process.
Should the report include passing criteria too?
It can. Some clients want a complete view: which criteria pass, which fail, and which are not applicable. This is especially useful when the report feeds into an ACR. For most audit deliverables, the report focuses on the issues identified, since those are what drive remediation.
A clear report is the difference between an audit that sits on a shelf and one that turns into a fixed product. Every column earns its place. Every row stands on its own.
For a structured audit report built around these standards, contact Accessible.org.
