appendix c accessibility standards

Appendix C: Accessibility Standards Reference

Listen to Episode 20: Accessibility Standards Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

WCAG, ARIA, and What They Mean for Your Contributions

This appendix gives you a working understanding of the accessibility standards that govern the web, GitHub's interface, and the projects you will contribute to. You do not need to memorize these - use this as a lookup when a PR review mentions a specific standard or success criterion.

Table of Contents

1. WCAG 2.2 - The Four Principles
2. Conformance Levels: A, AA, AAA
3. Key Success Criteria for Web Contributions
4. ARIA - Roles, States, and Properties
5. ARIA Landmark Roles
6. Common ARIA Patterns
7. How Standards Apply to GitHub Contributions
8. Testing Against Standards
9. Quick Reference: What to Check in a PR
10. Official References

1. WCAG 2.2 - The Four Principles

WCAG (Web Content Accessibility Guidelines) is organized around four principles, often abbreviated POUR:

Principle	Meaning	Example Failure
Perceivable	Information must be presentable to users in ways they can perceive	An image with no alt text - a screen reader user gets nothing
Operable	UI components and navigation must be operable	A button that only works on hover - keyboard users cannot activate it
Understandable	Information and operation must be understandable	An error message that says "Invalid input" with no explanation of what is wrong
Robust	Content must be robust enough to be interpreted by assistive technologies	Custom JavaScript widgets with no ARIA roles - screen readers cannot determine what they are

Every WCAG success criterion belongs to one of these four principles.

2. Conformance Levels: A, AA, AAA

Level	Requirement	Who targets this
A	Minimum accessibility - the baseline that removes the most severe barriers	Required by most accessibility laws
AA	Enhanced accessibility - removes significant barriers	Required by WCAG 2.2 compliance targets, most government and enterprise standards, GitHub's own accessibility commitment
AAA	Highest level - removes remaining barriers for the most niche cases	Not universally required; applied where feasible

Most open source projects, and GitHub itself, target WCAG 2.2 AA compliance. When you file an accessibility bug or review a PR, AA is the standard to reference.

3. Key Success Criteria for Web Contributions

These are the criteria you will most commonly encounter when contributing to web projects or reviewing GitHub interface changes.

Perceivable

Criterion	Level	What It Requires
1.1.1 Non-text Content	A	All images, icons, and non-text content have a text alternative (alt attribute, aria-label, etc.)
1.3.1 Info and Relationships	A	Structure conveyed visually (headings, lists, tables) is also conveyed programmatically
1.3.2 Meaningful Sequence	A	Reading order makes sense when CSS is removed
1.3.3 Sensory Characteristics	A	Instructions do not rely solely on shape, color, or position ("click the green button" fails this)
1.4.1 Use of Color	A	Color is not the only means of conveying information
1.4.3 Contrast (Minimum)	AA	Text has at least 4.5:1 contrast ratio against its background (3:1 for large text)
1.4.4 Resize Text	AA	Text can be resized up to 200% without loss of content or function
1.4.10 Reflow	AA	Content reflows at 400% zoom without horizontal scrolling
1.4.11 Non-text Contrast	AA	UI components and graphical objects have at least 3:1 contrast

Operable

Criterion	Level	What It Requires
2.1.1 Keyboard	A	All functionality is available via keyboard
2.1.2 No Keyboard Trap	A	Keyboard focus can always be moved away from any component
2.4.1 Bypass Blocks	A	A mechanism to skip repeated navigation (skip link)
2.4.2 Page Titled	A	Pages have descriptive titles
2.4.3 Focus Order	A	Focus follows a logical sequence
2.4.4 Link Purpose	A	Link text describes the destination ("Read more about issues" not just "Read more")
2.4.6 Headings and Labels	AA	Headings and labels describe their topic or purpose
2.4.7 Focus Visible	AA	Keyboard focus indicator is visible
2.4.11 Focus Appearance	AA (2.2 new)	Focus indicator meets minimum size and contrast
2.5.3 Label in Name	A	For controls with visible labels, the accessible name contains the visible text

Understandable

Criterion	Level	What It Requires
3.1.1 Language of Page	A	The default language is identified in the HTML (lang attribute)
3.2.1 On Focus	A	Receiving focus does not trigger unexpected context changes
3.2.2 On Input	A	Changing a setting does not cause unexpected changes unless the user is warned
3.3.1 Error Identification	A	Input errors are identified and described in text
3.3.2 Labels or Instructions	A	Labels or instructions are provided when user input is required
3.3.3 Error Suggestion	AA	When an error is detected, suggestions for correction are provided

Robust

Criterion	Level	What It Requires
4.1.1 Parsing	A	HTML/markup does not have errors that break AT interpretation
4.1.2 Name, Role, Value	A	All UI components have accessible names, roles, and states that can be programmatically determined
4.1.3 Status Messages	AA	Status messages (e.g. "item added to cart") are announced without receiving focus

4. ARIA - Roles, States, and Properties

WAI-ARIA (Accessible Rich Internet Applications) fills the gap between what HTML natively expresses and what complex interactive widgets require.

Three categories

Category	Purpose	Examples
Roles	What the element is	role="button", role="dialog", role="tab"
States	Current condition (can change)	aria-expanded="false", aria-checked="true", aria-disabled="true"
Properties	Stable characteristics	aria-label="Close dialog", aria-required="true", aria-describedby="hint-text"

Important rules

1. Don't use ARIA if native HTML suffices. A <button> is already a button - adding role="button" to a <div> is only needed when HTML semantics cannot be used.
2. All interactive ARIA widgets must be keyboard operable. Adding role="button" means you must also handle Enter and Space keypresses in JavaScript.
3. ARIA only affects the accessibility tree. It does not add visual styling or behavior - it only changes what assistive technologies announce.

5. ARIA Landmark Roles

Landmarks let screen reader users jump directly to major sections of a page. GitHub uses these extensively; screen reader users navigate between them with D (NVDA/JAWS) or the Rotor (VoiceOver).

Role	HTML Equivalent	Purpose
banner	<header>	Site-wide header
navigation	<nav>	Navigation links
main	<main>	Primary page content
complementary	<aside>	Supporting content
contentinfo	<footer>	Footer with copyright, links
search	<search>	Search functionality
form	<form> (with accessible name)	A significant form region
region	<section> (with accessible name)	A generic landmark with a label

When multiple landmarks of the same type appear on a page, each should have a unique aria-label so screen readers can distinguish them. GitHub's Issues list page, for example, has multiple navigation regions each with distinct labels.

6. Common ARIA Patterns

Accessible Button (when <button> cannot be used)

<div role="button" tabindex="0" aria-pressed="false" onclick="toggle()" onkeydown="handleKey(event)">
  Toggle
</div>

Accessible Form Field with Error

<label for="username">Username</label>
<input id="username" type="text" aria-describedby="username-error" aria-invalid="true">
<span id="username-error" role="alert">Username cannot be empty</span>

Live Region (status announcements)

<div aria-live="polite" aria-atomic="true">
  <!-- Content inserted here is announced automatically -->
  3 results found
</div>

Use aria-live="assertive" only for urgent interruptions (errors). Use "polite" for non-urgent status updates.

Expandable Section

<button aria-expanded="false" aria-controls="details-panel">
  Show details
</button>
<div id="details-panel" hidden>
  ...content...
</div>

When expanded: set aria-expanded="true" and remove the hidden attribute.

7. How Standards Apply to GitHub Contributions

When you contribute to an open source project on GitHub, you will encounter accessibility in several contexts:

Filing an Accessibility Bug

Reference the specific WCAG criterion. This makes the bug actionable:

Bad: "The button isn't accessible."
Good: "The 'Subscribe' button has no visible focus indicator, failing WCAG 2.4.7 Focus Visible (Level AA). When navigating by keyboard, there is no visual indication of where focus is."

Reviewing a PR for Accessibility

Checklist for any PR that touches HTML or UI:

• Do new images have alt attributes?
• Do new interactive elements work with keyboard only?
• Do new form fields have associated <label> elements?
• Are any new color-only indicators present?
• Does new dynamic content use aria-live if it updates without a page load?

Writing Accessible Documentation

Documentation in Markdown is converted to HTML. Accessible Markdown:

• Use heading levels in order (don't skip from H1 to H3)
• Write descriptive link text (not "click here")
• Add alt text to images: ![Bar chart showing 40% improvement in task completion](chart.png)
• Use actual lists (- or 1.) rather than faking them with symbols

8. Testing Against Standards

Automated Tools (catch ~30-40% of issues)

Tool	Use
axe DevTools	Browser extension - run on any page, get WCAG violations with criterion references
WAVE	Browser extension or web service - visual overlay showing issues
Lighthouse	Built into Chrome DevTools - accessibility audit with scores
IBM Equal Access Checker	Enterprise-grade browser extension

Manual Testing (catches the rest)

1. Keyboard-only navigation - unplug your mouse; can you do everything?
2. Screen reader walkthrough - navigate the feature with NVDA, JAWS, or VoiceOver
3. 200% zoom - does content reflow without horizontal scrolling?
4. High contrast mode - Windows High Contrast or macOS Increase Contrast; are all elements still visible?
5. Disable CSS - does the content still make sense in reading order?

9. Quick Reference: What to Check in a PR

Check	WCAG Criterion
New images have alt text	1.1.1
Heading levels are in order	1.3.1
Links have descriptive text	2.4.4
Interactive elements are keyboard accessible	2.1.1
Focus is visible on all interactive elements	2.4.7
Form fields have labels	1.3.1, 3.3.2
Error messages are descriptive	3.3.1, 3.3.3
Color is not the only indicator	1.4.1
Dynamic content updates use aria-live	4.1.3
New UI components have name, role, value	4.1.2

10. Official References

Resource	URL
WCAG 2.2 Full Specification	w3.org/TR/WCAG22
WCAG 2.2 Quick Reference	w3.org/WAI/WCAG22/quickref
Understanding WCAG 2.2	w3.org/WAI/WCAG22/Understanding
WAI-ARIA 1.2 Specification	w3.org/TR/wai-aria-1.2
ARIA Authoring Practices Guide	w3.org/WAI/ARIA/apg
WebAIM Contrast Checker	webaim.org/resources/contrastchecker
MDN Accessibility	developer.mozilla.org/en-US/docs/Web/Accessibility
GitHub Accessibility	accessibility.github.com

Return to: Resources | Appendix B - Screen Reader Cheat Sheet | Appendix A - Glossary