awesome-copilot/skills/create-web-form/references/accessibility.md

Web Accessibility Reference

A consolidated reference guide drawn from MDN Web Docs covering core accessibility concepts, authoring guidelines, safe browsing practices, ARIA-based widgets, and mobile accessibility requirements.

---

1. Accessibility Overview

Source: https://developer.mozilla.org/en-US/docs/Web/Accessibility

What Is Accessibility?

Accessibility (abbreviated as A11y -- "a" + 11 characters + "y") in web development means enabling as many people as possible to use websites, even when those people's abilities are limited in some way.

"The Web is fundamentally designed to work for all people, whatever their hardware, software, language, location, or ability. When the Web meets this goal, it is accessible to people with a diverse range of hearing, movement, sight, and cognitive ability." -- W3C

Key points:

• Technology makes things easier for many people.
• Technology makes things possible for people with disabilities.
• Accessibility spans physical, cognitive, hearing, movement, and sight abilities.

Core Principles

1. Semantic HTML -- Use correct elements for their intended purpose.
2. Keyboard Navigation -- Ensure full functionality without a mouse.
3. Assistive Technology Support -- Maintain compatibility with screen readers and other tools.
4. Perceivability -- Content must be perceivable through multiple senses.
5. Operability -- All functionality must be keyboard accessible.
6. Understandability -- Clear language and predictable behavior.
7. Robustness -- Works across diverse assistive technologies.

Beginner Tutorial Modules (MDN Learn Web Development)

Module	Description
What is Accessibility?	Groups to consider, tools users rely on, workflow integration
Accessibility Tooling and Assistive Technology	Tools for solving accessibility issues
HTML: A Good Basis for Accessibility	Semantic markup and correct element usage
CSS and JavaScript Best Practices	Accessible implementation of CSS and JS
WAI-ARIA Basics	Adding semantics for complex UI controls and dynamic content
Accessible Multimedia	Text alternatives for video, audio, and images
Mobile Accessibility	iOS/Android tools and mobile-specific considerations

Key Standards and Frameworks

• WCAG (Web Content Accessibility Guidelines) -- organized into Perceivable, Operable, Understandable, and Robust categories.
• ARIA (Accessible Rich Internet Applications) -- 53+ attributes and 87+ roles for adding semantic meaning to custom widgets.

---

2. Information for Web Authors

Source: https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Information_for_Web_authors

Guidelines and Regulations

ARIA Authoring Practices Guide (APG)

• Provider: W3C
• URL: https://www.w3.org/WAI/ARIA/apg/
• Design patterns and functional examples for accessible web experiences.
• Covers how to apply accessibility semantics to common design patterns and widgets.

Web Content Accessibility Guidelines (WCAG)

• Provider: W3C Web Accessibility Initiative (WAI)
• URL: https://www.w3.org/WAI/standards-guidelines/wcag/
• Important baseline guidelines being adopted by EU accessibility regulations.

ARIA on MDN

• Complete guides to ARIA roles, properties, and attributes.
• Best practices and code examples for each role.

How-to Guides

Guide	Provider	URL
Accessibility for Teams	U.S. General Services Administration	https://digital.gov/guides/accessibility-for-teams/
Accessible Web Page Authoring	IBM	https://www.ibm.com/able/requirements/requirements/

Automated Checking and Repair Tools

Browser Extensions

Tool	URL
HTML CodeSniffer	https://squizlabs.github.io/HTML_CodeSniffer/
aXe DevTools	Built into browser DevTools
Lighthouse Accessibility Audit	Chrome DevTools integrated
Accessibility Insights	https://accessibilityinsights.io/
WAVE	https://wave.webaim.org/extension/

Build-Process / Programmatic Testing

Tool	Description
axe-core	Accessibility engine for automated testing (dequelabs/axe-core)
eslint-plugin-jsx-a11y	ESLint plugin for JSX accessibility rules
Lighthouse Audits	Programmable audit runner (GoogleChrome/lighthouse)
AccessLint.js	Automated a11y linting library

Continuous Integration

• AccessLint (https://accesslint.com/) -- integrates with GitHub pull requests for automated accessibility review.

Testing Recommendations

Simulation and testing methods to employ:

• Color blindness simulation
• Low vision simulation
• Low contrast testing
• Zoom testing
• Keyboard-only navigation (disable the mouse)
• Touch-only testing
• Voice command testing
• Testing with a Web Disability Simulator browser extension

Best practice: Test with real users whenever possible.

---

3. Browsing Safely

Source: https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Browsing_safely

Conditions Addressed

Condition	Common Triggers
Vestibular Disorders	Motion, animations, parallax effects
Seizure Disorders	Flashing (3+ per second), flickering, high-contrast color changes
Photosensitivity	Color intensity, flashing, high contrast
Traumatic Brain Injury (TBI)	High cognitive load from color processing

CSS Media Feature: prefers-reduced-motion

Detects the user's OS-level preference for reduced motion.

@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}

CSS transition events that developers can listen to:

• transitionrun
• transitionstart
• transitionend
• transitioncancel

Platform-Level Browser Controls

Platform	Setting	Notes
Safari Desktop (10.1+)	Disable Auto-Play	Does not affect animated GIFs
iOS Safari (10.3+)	Reduce Motion (OS Accessibility settings)	GIFs unaffected
Firefox	image.animation_mode set to "none"	Disables all animated GIFs
Reader Mode (various)	Content Blockers, text-to-speech, font/zoom	Reduces distractions

Useful Browser Extensions

Extension	Purpose	Browser
Gif Blocker	Blocks all GIFs	Chrome
Gif Scrubber	Pause/play/scrub GIFs like a video	Chrome
Beeline Reader	Grayscale mode, dyslexia-friendly fonts, contrast	Chrome, Edge, Firefox

Operating System Accessibility Features

Windows 10:

• Settings > Ease of Access > Display -- Turn off animations.
• Settings > Ease of Access > Display > Color Filters -- Toggle grayscale.
• Grayscale reduces cognitive load for TBI, photosensitive epilepsy, and other conditions.

macOS:

• System Preferences > Accessibility > Display -- "Reduce motion" option.

WCAG Compliance: Success Criterion 2.3.1

Three Flashes or Below Threshold -- content must not flash more than three times per second unless the flash is below the general flash and red flash thresholds.

Best Practices for Developers

Do:

• Support the prefers-reduced-motion media query.
• Keep flashing below 3 times per second.
• Provide play/pause controls for all animations.
• Test with OS accessibility features enabled.

Do not:

• Auto-play videos or animations without user controls.
• Use high-frequency flashing or strobing effects.
• Assume all users can tolerate motion.

Implementation Checklist

• Add @media (prefers-reduced-motion: reduce) rules to CSS.
• Disable auto-play animations when the user preference is set.
• Ensure GIFs have pause controls.
• Test in Windows and macOS accessibility modes.
• Validate against WCAG 2.3.1 (Three Flashes criterion).

---

4. Accessible Web Applications and Widgets

Source: https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Accessible_web_applications_and_widgets

The Problem

Custom JavaScript widgets (sliders, menu bars, tabs, dialogs) built with generic HTML elements like <div> and <span> lack semantic meaning for assistive technologies. Dynamic content changes may not be detected by screen readers.

ARIA (Accessible Rich Internet Applications)

ARIA fills the gap between standard HTML and desktop-style UI controls with three types of attributes:

1. Roles -- Describe widgets not natively available in HTML (sliders, menu bars, tabs, dialogs).
2. Properties -- Describe characteristics (draggable, required, has popup).
3. States -- Describe current interaction state (busy, disabled, selected, hidden).

Important: Prefer semantic HTML elements over ARIA when available. ARIA is a progressive enhancement for dynamic components.

Example: Tabs Widget

Without ARIA (non-accessible):

<ol>
  <li id="ch1Tab">
    <a href="#ch1Panel">Chapter 1</a>
  </li>
  <li id="ch2Tab">
    <a href="#ch2Panel">Chapter 2</a>
  </li>
</ol>

<div>
  <div id="ch1Panel">Chapter 1 content goes here</div>
  <div id="ch2Panel">Chapter 2 content goes here</div>
</div>

With ARIA (accessible):

<ol role="tablist">
  <li id="ch1Tab" role="tab">
    <a href="#ch1Panel">Chapter 1</a>
  </li>
  <li id="ch2Tab" role="tab">
    <a href="#ch2Panel">Chapter 2</a>
  </li>
</ol>

<div>
  <div id="ch1Panel" role="tabpanel" aria-labelledby="ch1Tab">
    Chapter 1 content goes here
  </div>
  <div id="ch2Panel" role="tabpanel" aria-labelledby="ch2Tab">
    Chapter 2 content goes here
  </div>
</div>

Common ARIA State Attributes

Attribute	Purpose
aria-checked	State of checkbox or radio button
aria-disabled	Visible but not editable/operable
aria-grabbed	"Grabbed" state in drag-and-drop
aria-selected	Selected state of an element
aria-expanded	Whether expandable content is open
aria-pressed	Pressed state of a toggle button

Use ARIA states to indicate UI state and CSS attribute selectors to style accordingly.

Visibility Management with aria-hidden

<div id="tp1" class="tooltip" role="tooltip" aria-hidden="true">
  Your first name is optional
</div>

div.tooltip[aria-hidden="true"] {
  display: none;
}

function showTip(el) {
  el.setAttribute("aria-hidden", "false");
}

Role Changes

Never change an element's ARIA role dynamically. Instead, replace the element entirely:

// Correct: swap elements
// View mode
<div role="button">Edit this text</div>

// Edit mode: replace with an input
<input type="text" />

Keyboard Navigation Best Practices

Key	Expected Behavior
Tab / Shift+Tab	Move focus into and out of the widget
Arrow Keys	Navigate between items within the widget
Enter / Spacebar	Activate the focused control
Escape	Close menus or dialogs
Home / End	Jump to first or last item

Focus management considerations:

• Maintain focus order that matches visual layout.
• Use tabindex="0" to make custom elements keyboard accessible.
• Avoid tabindex > 0 (breaks natural tab order).
• Update the visual focus indicator for keyboard users.
• Move focus programmatically when opening dialogs or modals.

Key ARIA Attributes for Interactive Widgets

Labeling and Description:

Attribute	Usage
aria-label	Direct text label
aria-labelledby	References the element that labels this one
aria-describedby	References additional descriptive text
aria-description	Inline description text

Relationships:

Attribute	Usage
aria-controls	This element controls another element
aria-owns	Establishes parent-child relationships
aria-flowto	Defines logical reading order

Widget Behavior:

Attribute	Usage
aria-haspopup	Has a popup (menu, listbox, dialog, grid, tree)
aria-expanded	Expandable content state (true/false)
aria-modal	Modal dialog (true)
aria-live	Live region announcements (polite, assertive, off)
aria-busy	Loading or processing state (true/false)

Live Regions for Dynamic Content

<div aria-live="polite" aria-atomic="true">
  Updates will be announced to screen readers
</div>

• aria-live="polite" -- announce when convenient.
• aria-live="assertive" -- announce immediately.
• aria-atomic="true" -- announce the entire region, not just the changed part.

---

5. Mobile Accessibility Checklist

Source: https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Mobile_accessibility_checklist

A checklist of accessibility requirements for mobile app developers targeting WCAG 2.2 AA compliance.

Color

• Normal text: minimum 4.5:1 contrast ratio (less than 18pt or 14pt bold).
• Large text: minimum 3:1 contrast ratio (at least 18pt or 14pt bold).
• Information conveyed via color must also be available through other means (e.g., underlines for links).

Visibility

• Do NOT hide content exclusively with zero opacity, z-index ordering, or off-screen placement.
• Use the hidden HTML attribute, visibility, or display CSS properties to truly hide content.
• Avoid aria-hidden unless absolutely necessary.
• Critical for single-page apps where multiple views/cards may overlap.

Focus

• Standard controls (links, buttons, form fields) are focusable by default.
• Custom controls must have an appropriate ARIA Role (e.g., button, link, checkbox).
• Focus order must be logical and consistent.

Text Equivalents

• Provide text alternatives for all non-text elements using alt, title, aria-label, aria-labelledby, or aria-describedby.
• Avoid images of text.
• Visible UI component text must match the programmatic name (WCAG 2.1: Label in Name).
• All form controls must have associated <label> elements.

Handling State

• Standard controls: the operating system handles radio buttons and checkboxes.
• Custom controls must communicate state changes via ARIA States:
  • aria-checked
  • aria-disabled
  • aria-selected
  • aria-expanded
  • aria-pressed

Orientation

• Content must not be restricted to portrait or landscape unless essential (e.g., a piano app or bank-check scanner).
• Reference: WCAG 2.1 Orientation (https://www.w3.org/WAI/WCAG21/Understanding/orientation.html).

General Guidelines

App Structure:

• Always provide an app title.
• Use a proper heading hierarchy without skipping levels:

<h1>Top level heading</h1>
  <h2>Secondary heading</h2>
  <h2>Another secondary heading</h2>
    <h3>Low level heading</h3>

ARIA Landmark Roles:

Use landmarks to describe app or document structure:

• banner
• complementary
• contentinfo
• main
• navigation
• search

Touch Events (WCAG 2.1: Pointer Cancellation):

1. Avoid executing functions on the down-event.
2. If unavoidable, complete the function on the up-event with an abort mechanism.
3. If unavoidable, ensure the up-event can undo the down-event action.
4. Exceptions: game controls, virtual keyboards, real-time feedback.

Touch Target Size:

• Targets must be large enough for reliable user interaction.
• Reference: BBC Mobile Accessibility Guidelines for specific sizing recommendations (https://www.bbc.co.uk/accessibility/forproducts/guides/mobile/target-touch-size).

---

Additional Resources

Resource	URL
W3C Accessibility Standards	https://www.w3.org/standards/webdesign/accessibility
WAI Interest Group	https://www.w3.org/WAI/about/groups/waiig/
ARIA Specification	https://w3c.github.io/aria/
WAI-ARIA Authoring Practices	https://www.w3.org/WAI/ARIA/apg/
WCAG 2.1 Understanding Docs	https://www.w3.org/WAI/WCAG21/Understanding/
IBM Accessibility Requirements	https://www.ibm.com/able/requirements/requirements/
Accessibility Insights	https://accessibilityinsights.io/
WAVE Evaluation Tool	https://wave.webaim.org/extension/