This checklist helps you test issue templates, PRs, and GitHub workflows to ensure they're usable by people with disabilities (especially screen reader users).
Use before deploying any new issue template or form.
- Every form field has a visible label
- Label text is clear and describes what's needed (not "Please enter")
- Required fields are marked and announced as required
- Help text is associated with each field (not just placeholder text)
- No fields rely on color alone to indicate required/error status
- Form inputs are in logical order (top to bottom)
- Dropdown options are readable and include blank option or instruction
- Checkboxes and radio buttons are grouped and labeled
- No more than 6-8 required fields (reduces cognitive load)
- Preview or review step before submission (allows verification)
- Markdown section explains what's needed and why
- Instructions use simple language (8th grade reading level)
- Headings are in order (H2, H3, H4 - not H2, H4)
- Links have descriptive text (not "click here")
- Code examples are formatted clearly (not in plain text)
- YAML passes syntax validation (https://www.yamllint.com/)
- No trailing spaces or mixed indentation
- All required fields present:
name:,description:,body: - Field IDs are unique and lowercase with hyphens (e.g.,
browser_type)
- Prepare: Have form open in browser with screen reader ready
- Choose: Test with NVDA (Windows), JAWS (Windows), or VoiceOver (macOS)
- Record: Note any issues for fixing
1. Press NVDA+Space to enable browse mode on page
2. Press H to navigate to first heading
3. Use H repeatedly to scan all headings (should be H1 → H2 → H3, not jumps)
4. Press B to find buttons, forms
5. Navigate to form field: Tab or arrow keys
6. Screen reader should announce:
"[Label text] [field type] [required if applicable]"
Example: "Email address edit text, required"
7. Tab through every field in order
8. Check Tab order makes sense (left-to-right, top-to-bottom)
9. Verify instructions between fields are heard
What to listen for:
- Every field label is announced
- "Required" is announced for required fields
- No fields are skipped
- Field types are clear (edit text, dropdown, checkbox, etc.)
- Help text is read before or near the field
1. Press Spacebar to enter browse mode
2. Press Insert+F6 to open headings list
- Verify headings are in order (1 → 2 → 3, no jumps)
- Close list (Escape)
3. Press Insert+F5 to open forms list
- Should see every field
- Close list
4. Tab through form field by field
5. JAWS should announce:
"[Label] [field type] [required if applicable]"
6. Press Insert+Down to read entire form (simulates form-scanning)
What to listen for:
- Form start is announced
- All fields are listed in Forms List
- Required fields say "required"
- Field order matches logical reading order
- No unlabeled fields
1. Press VO+U to open Web Rotor
2. Navigate to Form Controls section
- Should list all fields
- Verify count matches expected fields
3. Navigate to Headings section
- Check heading hierarchy (no jumps)
4. Press VO+Right arrow to move through page
- Should hear each field label before field
5. Press VO+Space on field to interact
6. VoiceOver should announce:
"[Label], [field type] [required if applicable]"
What to listen for:
- Rotor shows all form controls
- Heading levels are correct (no 1 → 3 jumps)
- Field labels are adjacent to fields
- Instructions are readable
- Grouped label describes the entire group
- Individual labels describe each option
- Screen reader announces number of options
- Example: Screen reader says: "Browser, radio button group, 3 items. Chrome, radio button, not selected"
Test: Tab to group, use arrow keys to select. Screen reader should guide you clearly.
- Visible label above or adjacent to dropdown
- Dropdown shows currently selected value
- Opening dropdown announces all options (or "expandable menu")
- Options include instruction or blank option if optional
- Focus style is visible (not invisible on dark backgrounds)
Test: Tab to dropdown, press Down/Space to open, arrow through options.
- Link text describes where it goes (not "click here", "link", "read more")
- Button text describes what happens (not "submit", "go", "continue")
- Focuses visible with keyboard (Tab key shows clear highlight)
- No links that are only images (images need alt text)
Test: Press Tab to navigate, read labels aloud.
- Label directly associated with field (via
labeltag or aria-label) - Placeholder text is NOT a substitute for label
- Example: Bad: Empty field with gray "Enter email" (disappears when you type)
- Example: Good: Visible label "Email address:" + field
Test: Tab to field, screen reader announces label, then focus moves into field.
- Help text appears visually near the field
- Help text is announced by screen reader (not hidden)
- Instructions use simple language
- No abbreviations without explanation
Test: Tab to field, screen reader should announce label, field type, help text, and required status.
- Text contrast is 4.5:1 or higher (WCAG AA for normal text)
- Color is not the only way to show information
- Example: Bad: "Red fields are errors" (only color indicates error)
- Example: Good: "Error" label + red color + error icon
- Required fields marked with or "required" text (not just color)
- Disabled fields are visually distinct
Test: Use WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
Test WITHOUT using the mouse.
- Tab key navigates to all interactive elements
- Tab order follows logical reading order (left-to-right, top-to-bottom)
- Shift+Tab goes backwards
- Focus indicator is visible (not hidden or very faint)
- Can activate buttons with Enter or Space
- Can select radio buttons and checkboxes with arrow keys
- Can open dropdowns with Space or Down arrow
- Can submit form with Enter from submit button
Test: Close trackpad, use Tab/Shift+Tab/Enter/Space only.
- Form is readable on small screens (mobile, tablet)
- Form is usable with touch (buttons large enough: 44x44px minimum)
- Form labels don't disappear on narrow screens
- Touch targets don't overlap
- No horizontal scrolling required to use form
Test: Resize browser to mobile width (375px), or use phone/tablet to fill form.
- Instructions use simple, clear language (avoid jargon)
- No unexplained abbreviations (spell out first use, then abbreviate)
- Text can be enlarged to 200% without breaking layout
- If translated, consider cultural appropriateness of images/phrasings
Test: Select browser zoom 200% (Ctrl+Plus / Cmd+Plus), or use browser reader mode.
- All form fields have labels
- Required fields marked and announced
- Tab order is logical
- Focus styles are visible
- Color contrast is adequate (4.5:1 minimum)
- Heading hierarchy is correct
- YAML syntax is valid
- Tested with at least 1 screen reader (NVDA, JAWS, or VoiceOver)
- Keyboard-only workthrough (no mouse)
- Mobile/responsive check
- Plain language review
- Tested with all 3 screen readers
- Tested with multiple browsers (Chrome, Firefox, Safari, Edge)
- Tested with actual users with disabilities
- Performance tested (forms load quickly)
| Failure | What to Check | How to Detect |
|---|---|---|
| No field labels | Screen reader announces field but not what it's for | Tab to field; screen reader should say "[Label] [field type]" |
| Bad heading hierarchy | Heading jumps from H1 to H3 (confusing outline) | Use screen reader heading list (NVDA: not in list) |
| Color-only errors | Error only shown in red, not marked with text | Add error to optional field; look for text + color |
| Invisible focus | Can't see which element has keyboard focus | Tab through form; focus outline should be clear |
| Unlabeled fields | Dropdown or input has no visible/announced name | Tab to field; screen reader says "(blank)" |
| Links say "click here" | Not descriptive; screen reader only hears "click here" | Read link text aloud; should make sense out of context |
| No skip link | Can't skip repetitive navigation | Press Tab to first element; should offer "skip to content" |
- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/ (color accessibility)
- WAVE Browser Extension: https://wave.webaim.org/extension/ (errors & warnings)
- Axe DevTools: https://www.deque.com/axe/devtools/ (comprehensive audit)
- Lighthouse (built into Chrome): F12 → Lighthouse → Accessibility (score & feedback)
- NVDA (free): https://www.nvaccess.org/ (Windows)
- JAWS (trial available): https://www.freedomscientific.com/ (Windows)
- VoiceOver (built-in): macOS/iOS
- Keyboard Testing: No tools needed - just don't use mouse!
- Screen Reader Commands: See
docs/appendix-b-screen-reader-cheatsheet.md - WCAG Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
- Get Help: Open an issue with accessibility testing results
When you find an accessibility problem, document it:
Title: [Accessibility] Form label missing on email field
Description:
When tabbing to the email input on the issue template, the screen reader
announces "edit text, required" but does not announce what the field is for.
Steps to reproduce:
1. Open [template file/page]
2. Tab to email field
3. Listen to screen reader announcement
Expected:
Screen reader should announce: "Email address, edit text, required"
Actual:
Screen reader announces: "Edit text, required"
Screen reader tested: NVDA 2025.3.3
Browser: Chrome 130
OS: Windows 11
This repository includes a build system that converts all Markdown files to HTML (see BUILD.md). If participants will use the HTML versions, test them separately:
- Each HTML page has exactly one
<h1>element - Heading levels don't skip (no
<h1>→<h3>jumps) - Navigation footers don't break the heading outline
- Internal links resolve correctly (
.mdlinks are converted to.html) - Anchor links (
#section-name) scroll to the correct position - External links open and are not broken
- The
<main>element wraps the primary content - Navigation elements are properly structured
- Screen reader can identify page regions using landmarks (
Dkey in NVDA/JAWS)
- Run pages through the W3C HTML Validator - check for errors
- Run pages through WAVE - check for accessibility errors
- Verify syntax-highlighted code blocks are readable (not color-only)
Quick test: Open html/index.html in a browser, enable your screen reader, and navigate using H (headings) and K (links). Every heading and link should be announced clearly.
- Having trouble testing? See
TROUBLESHOOTING.md - Need screen reader help? See
docs/appendix-b-screen-reader-cheatsheet.md - Want resources? See
docs/appendix-u-resources.md
Last updated: February 2026
Accessibility is foundational to inclusive workflows.