ada-compliance

name	ada-compliance
description	Use this skill when implementing, auditing, or documenting ADA-aligned web accessibility using WCAG 2.2 AA expectations for websites, web apps, UI components, forms, media, navigation, dynamic content, and semantic HTML.

ADA and WCAG Compliance

Use this skill when a project needs accessibility requirements, accessibility review, or ADA-aligned website behavior. Treat WCAG 2.2 AA as the default target unless the user specifies a different standard. WCAG 2.1 AA may be the minimum requirement in some contexts, but this repository should prefer the more current AA target when feasible.

Before declaring a page, component, or workflow accessible, verify the checklist below or document any intentionally deferred items in docs/checklist.md.

Images and Non-Text Content

• Meaningful images have descriptive alt text.
• Decorative images use alt="" or are implemented as decorative CSS backgrounds.
• Complex visuals such as charts, maps, and diagrams have an accessible text summary or extended description.
• Images of text are avoided unless essential, such as logos or brand marks.
• Linked images describe the link destination through their accessible name.

Audio and Video

• Prerecorded video includes synchronized captions.
• Audio-only content includes a text transcript.
• Video communicates important visual-only information through audio description or adjacent text.
• Live audio or video includes captions when required by the project.
• Auto-playing audio longer than 3 seconds has a visible pause, stop, or mute control.

Structure and Semantics

• Pages use semantic landmarks such as header, nav, main, section, article, aside, and footer where appropriate.
• Each page has a logical heading hierarchy.
• Headings, labels, and control names are descriptive.
• Lists use list markup, not visual-only line breaks.
• Data tables use captions and scoped headers when needed.
• The document has the correct lang attribute.
• Any content in another language has a local lang attribute.
• Content reads in a logical order without CSS.

Color and Visual Design

• Normal text has at least 4.5:1 contrast against its background.
• Large text has at least 3:1 contrast against its background.
• Non-text UI elements and graphical state indicators have at least 3:1 contrast.
• Color is not the only way to communicate errors, success, selection, required fields, or status.
• Content remains readable and functional at 200% zoom.
• Content reflows at 320px width without horizontal scrolling except for genuinely two-dimensional content such as data tables.
• User-adjusted text spacing does not break content or controls.

Keyboard and Navigation

• All functionality works with a keyboard.
• Focus never becomes trapped unless the user is inside a modal or equivalent controlled interaction, and an escape path exists.
• Every interactive element has a visible focus indicator.
• Focused elements are not hidden behind sticky headers, overlays, or bottom bars.
• A skip link or equivalent bypass mechanism exists for repeated navigation.
• Tab order follows the logical reading and interaction order.
• Single-character keyboard shortcuts can be disabled, remapped, or limited to focused contexts.
• Pointer targets meet WCAG target-size expectations, and important touch targets should follow the larger mobile guidance in accessibility-mobile.

Forms

• Every form input has a visible, programmatically associated label.
• Required fields are identified without relying on color alone.
• Error messages are specific, visible, and available to assistive technology.
• Error suggestions are provided when possible.
• Inputs that collect personal data use appropriate autocomplete attributes.
• Legal, financial, account, or test submissions allow review, confirmation, or reversal when required.
• Authentication does not rely on inaccessible puzzles or memorization tasks without an accessible alternative.
• Previously entered information is reused when re-entry would otherwise be required.

Links and Buttons

• Link text is meaningful on its own or in its immediate programmatic context.
• Identical link text does not point to different destinations unless context makes the difference clear.
• Buttons have descriptive accessible names.
• Links that open new tabs, download files, or trigger unusual behavior communicate that behavior.

Page-Level Requirements

• Every page has a unique, descriptive <title>.
• Users have more than one way to find important pages when the site has multiple pages.
• Navigation appears in consistent locations and order.
• Components with the same function are consistently labeled.
• Help, contact, or support options are consistently placed when present.
• No content flashes more than three times per second.

Motion and Dynamic Content

• Auto-moving, blinking, or scrolling content can be paused, stopped, or hidden.
• Orientation is not locked unless the use case requires it.
• Gesture interactions have single-pointer or keyboard alternatives.
• Device-motion interactions have control alternatives and can be disabled.
• Tooltips and popups can be dismissed, hovered, and focused without losing content unexpectedly.
• Drag-and-drop interactions have an accessible alternative.
• Status messages are announced with appropriate ARIA live regions without stealing focus.

Code and Compatibility

• HTML is valid enough to preserve accessibility tree behavior.
• Custom components expose accurate name, role, state, and value.
• Native HTML controls are preferred over ARIA when they meet the need.
• Context changes do not happen automatically on focus.
• Form controls do not submit or navigate without deliberate user action.
• iframes and embedded content have descriptive title attributes.
• Accessibility checks include automated tooling and manual keyboard review.