Skip to content

WCAG: Known Issues and Solutions

Jump to bottom
Ryan Chase edited this page Feb 11, 2026 · 23 revisions

WAVE Accessibility

  • While conducting audits of the TDM Calculator, auditors should refer to the Known Issues index to confirm if we have encountered a specific WAVE Error
  • If a known issue cannot be found, then the auditor should use the WAVE: Known Accessibility Issue template specified on this page to create a new corresponding page
Table of Contents

Known Issues Wiki Page Template

The wiki pages created from this template will be used for future audits (across many teams) so that volunteers can easily identify and refer to technical solutions to WAVE accessibility errors.

Instructions

  1. Replace all bracketed [placeholders] with actual content
  2. Update the date in YYYY-MM-DD format
  3. Fill in the WAVE Tool Reference section with content from the official WAVE documentation
  4. Provide specific details in the TDM Solution section based on your issue and PR
  5. Add actual screenshot URLs to replace IMAGE_URL placeholders
  6. Add all contributor GitHub handles in the Credits section (wiki page author, PR author and reviewers)
  7. Remove or add screenshot sections as needed

Wiki Page Template

Copy/paste this template into the new wiki page editor:

Title 
WCAG: [REPLACE WITH WAVE CATEGORY]-[REPLACE WITH WAVE ERROR NAME]
Body 
# WAVE Known Accessibility Issue: [REPLACE WITH WAVE CATEGORY] - [REPLACE WITH WAVE ERROR NAME]
- WAVE Category: [REPLACE WITH WAVE CATEGORY]
- WAVE Error: [REPLACE WITH WAVE ERROR NAME]

## WAVE Error guidance

WAVE Tool's Reference material on [REPLACE WITH WAVE ERROR NAME] may not specifically address your problem.  We provide it here for optional reading.

<details><summary>Click to see WAVE Tool Reference</summary>
<p>

<!-- Note For Wiki Author: WAVE Tool text content will use text that break markdown generation for the details dropdown. If the copy/pasted text includes angle brackets, surround them with backticks to avoid this problem. -->

### WAVE Category
[REPLACE WITH WAVE CATEGORY]

### WAVE Error
[REPLACE WITH WAVE ERROR NAME]

### What It Means
[REPLACE WITH WAVE CONTENT FOR What It Means]

### Why It Matters
[REPLACE WITH WAVE CONTENT FOR Why It Matters]

### What To Do
[REPLACE WITH WAVE CONTENT FOR What To Do]

### The Algorithm... in English
[REPLACE WITH WAVE CONTENT FOR The Algorithm... In English]

### Standards and Guidelines
[REPLACE WITH WAVE CONTENT FOR Standards and Guidelines]

<!-- WIP JUMP TO -->

</p>
</details> 

## Example of a DOM Snippet Generated From WAVE Tool

> ```html
> [HTML snippet showing the problematic code structure that WAVE detected]
> ```


## TDM Error guidance

The following material covers how the TDM team has provided a solution to the [Error] WAVE error.

### TDM Calculator Page Details
- TDM Page name: [Page Name or "ALL"]
- TDM Staging URL: [URL or "N/A"]
- Required User Role: [Visitor/Logged in user/Admin/Security Admin]
### TDM Calculator Issue and PR details
- Related GitHub Issue(s):
  - [Issue URL]
- Related Pull Request(s):
  - [PR URL or "Add once PR is created for this fix (PR # TBD)"]
- React Component(s)
  - `[file/path/to/Component.jsx]`

### TDM Solution

#### What is the specific problem that was occurring?
[Detailed explanation of the specific accessibility problem, including context about when/where it occurs, what elements are involved, and why it's problematic for assistive technology users]

#### What is the proposed solution to this problem?
[A few sentences describing the fix. "Why the Fix Works" comes later (see below). If there are lots of instructions required to explain the solution, include them in Developer Resources below]

#### Step-By-Step Guide
<!-- Write N/A if this does not apply -->


<details><summary>Click to see step-by-step guide</summary>
<p>

[ADD DETAILED INSTRUCTIONS HERE]

</p>
</details> 

#### Other Technical Details
<!-- Write N/A if this does not apply -->

<details><summary>Click to see other technical details</summary>
<p>

[ e.g. Prop References, Return Value ]

</p>
</details> 

#### Code Snippet
```jsx
// [file/path/to/Component.jsx]

[Code example showing the fix/solution]
```

#### Why the Fix Works
[Explanation of how the code changes resolve the accessibility issue and why this approach was chosen]

#### Where this solution is applicable 
- [Context or scenario 1 where this solution applies]
- [Context or scenario 2 where this solution applies]
- [Additional contexts as needed]

#### Screenshots of WAVE Error

<details><summary>1. [Descriptive Title for Screenshot Set 1]</summary>

<img width="400" height="400" alt="Image" src="https://github.com/user-attachments/assets/123456789" />

</p>
</details> 

## Credits/Authors
All HfLA members who contributed to this wiki page and/or contributed to Pull Requests that provided solutions for this page.

- [Contributors]

Accessibility Known Issues Index

Solutions Index

Drafts

Known Issues (Needs drafting and Wiki Pages)

Other Related Pages

https://github.com/hackforla/tdm-calculator/wiki/Accessibility-Audits

Home

Introduction to the Project

Joining the TDM Calculator Team

After you have read the info for all joining team members, read the pages for your practice area

Product Documentation

Software Architecture and Development

Clone this wiki locally