Issue Reporting Guide
A comprehensive guide to reporting accessibility issues. Here you'll find detailed explanations for each input field, demo logs of reported issues, and guidelines for bulk importing audit files. The required fields include Location, Page URL, Environment, Issue,WCAG, andRecommendation. Optional fields such as Priority, Status (defaults to "Not Started" with allowed statuses: In progress, Completed, On Hold, Not Applicable, Not Started) and Notes may be provided.
Getting Started
Follow this guide to understand how to fill each field and how to structure your audit file for bulk importing>Additional mapping options will be provided in future updates.
Field Descriptions
Location
Indicates where the issue is found within the interface. Use a hierarchical approach (e.g., "Header > Navigation > Dropdown Menu") and include component names and unique identifiers if available.
- Provide specific area details
- Maintain a logical structure
- Reference unique IDs if applicable
Examples:
| Good Example | Poor Example |
|---|---|
| "Main Navigation - Search Bar" | "Top" |
| "Footer - Newsletter Signup" | "Footer" |
Page URL
The complete URL of the page where the issue is observed. Ensure that the URL is valid and includes the protocol (http:// or https://).
- Include full URL (e.g., https://example.com/page)
- Do not omit the protocol
- Double-check for typos
Environment
Describes the browser and operating system where the issue was observed. This helps in replicating and debugging the problem.
- Include browser name and version
- Include operating system details
- Mention device type if relevant
Example: "Chrome 120, Windows 11"
Issue
A clear and concise description of the accessibility issue. Focus on what's not working and how it affects user experience.
- Describe the problem precisely
- Indicate which user group is impacted
- Mention any error messages if applicable
Example: "The search input field lacks an aria-label, making it inaccessible for screen readers."
WCAG
Enter the WCAG success criterion that this issue violates. We follow the criteria 4.1.2 Name, Role, Value (Level A) for accessibility compliance.
Format: [Principle] [Guideline.Success_Criterion] [Level] - [Name]
Example: "4.1.2 Name, Role, Value (Level A)"
Recommendation
Provide a suggested solution or workaround for the reported issue. This may include code changes, configuration adjustments, or design updates.
- Explain the fix clearly
- Include code snippets if applicable
- Mention any testing or verification steps
Example: "Add a visually hidden label using aria-label to the search field."
Impact
A measurement (out of 100) that quantifies the potential negative effect of an accessibility issue on users. Higher values indicate more severe impact on user experience.
- Automatically calculated based on WCAG criteria
- Considers number of affected users
- Factors in severity of functional limitation
- Takes into account the importance of the affected feature
Impact Scale:
80-100: Critical - Prevents use of core functionality
60-79: High - Significantly hinders important functionality
40-59: Medium - Causes difficulty but has workarounds
0-39: Low - Minor impediment to user experience
Risk Factor
A score (out of 10) that assesses the potential legal, financial, and reputational risk associated with not addressing the accessibility issue.
- Automatically calculated based on WCAG compliance level
- Considers legal requirements in target markets
- Factors in compliance with regulatory standards
- Assesses potential for complaints or litigation
Risk Factor Scale:
8-10:
High risk - Potential legal liability, significant compliance issue
6-7:
Moderate risk - May attract complaints, non-compliance with standards
4-5:
Low risk - Minor compliance issues with less severe consequences
1-3:
Minimal risk - Best practice recommendations
Notes
Additional context or comments regarding the issue. Use this field to document any observations or temporary workarounds.
Example: "Tested on multiple devices. Issue not reproducible on Android."
Bulk Import Template
Audit File Format
Use this Excel template for bulk importing accessibility issues. The required columns are Location,Page URL,Environment, Issue,WCAG, andRecommendation. Optional fields include Priority, Status, and Notes. If not provided, Priority defaults toNone and Status defaults toNot Started (allowed statuses: In progress, Completed, On Hold, Not Applicable, Not Started).
| Column Name | Required | Format | Example |
|---|---|---|---|
| Location | Required | Text | "Header > Navigation > Search Bar" |
| Page URL | Required | URL | https://example.com/home |
| Environment | Required | Text | "Chrome 120, Windows 11" |
| Issue | Required | Long Text | "Input field missing aria-label" |
| WCAG | Required | Text | "4.1.2 Name, Role, Value (Level A)" |
| Recommendation | Required | Long Text | "Add aria-label to input" |
| Priority | Optional | high/medium/low (defaults to None) | "high" |
| Status | Optional | In progress / Completed / On Hold / Not Applicable / Not Started (defaults to Not Started) | "Not Started" |
| Notes | Optional | Long Text | "Tested on multiple devices" |
Excel Upload Instructions:
- The Excel file should contain only one sheet.
- If multiple sheets exist, ensure the first sheet contains all the issues.
- If the sheet order is different, make sure a sheet is named Audit.
- Preference is as follows: if one sheet exists, use it; if multiple, check for a sheet named Audit; if not found, extract issues from the first sheet. If all fails, an error is shown.
Demo: Logged Issues
Issues Log
Below is a demo of how a few issues are logged. Only the required fields are displayed here, with Priority and Status defaulted to "None" and "Not Started" (unless updated). Impact (out of 100) and Risk Factor (out of 10) are automatically populated based on the WCAG criteria of the issue.
| Location | Page URL | Environment | Issue | WCAG | Recommendation | Impact | Risk | Priority | Status |
|---|---|---|---|---|---|---|---|---|---|
| Header > Navigation > Search Bar | https://example.com/home | Chrome 120, Windows 11 | Search input field lacks proper label causing screen readers to misinterpret its function. | 4.1.2 Name, Role, Value (Level A) | Add a visually hidden label or aria-label to the search input. | 85/100 | 8/10 | None | Not Started |
| Footer > Newsletter Signup | https://example.com/contact | Firefox 115, macOS Monterey | Button color contrast is too low making it hard to read for users with low vision. | 4.1.2 Name, Role, Value (Level A) | Increase the contrast ratio by adjusting the button background color. | 70/100 | 6/10 | None | In progress |
| Product Page > Details Section | https://example.com/product/123 | Safari 14, iOS 15 | The product details are not announced correctly by screen readers due to missing ARIA roles. | 4.1.2 Name, Role, Value (Level A) | Implement ARIA roles and properties to ensure accessibility. | 90/100 | 9/10 | None | On Hold |
Showing3 issues
Impact Score Risk Factor