Complete Accessibility Rules Reference

ARIA attributes must be allowed for the element's role

An element has ARIA attributes that are not allowed for its role. This can confuse assistive technologies and provide incorrect information to users.

ARIA Role Must Be Appropriate for Element

The `role` attribute must be appropriate for the HTML element on which it is used. Some ARIA roles are not allowed on certain HTML elements because the element's native semantics conflict with or override the ARIA role, or because the combination creates invalid or nonsensical accessibility information.

ARIA Hidden Elements Must Not Contain Focusable Elements

Elements with `aria-hidden="true"` must not contain focusable elements. When an element is hidden from assistive technologies using `aria-hidden="true"`, any focusable descendants within it create a confusing experience where keyboard users can focus on elements that screen readers cannot perceive or announce.

Elements with ARIA roles must have all required attributes

An element with an ARIA role is missing one or more required ARIA attributes. Assistive technologies cannot properly interpret the element without these required attributes.

Elements with ARIA Roles Must Have Required Children

Certain ARIA roles require specific child roles to be present to create valid accessibility structures. For example, a `listbox` must contain `option` elements, a `tablist` must contain `tab` elements, and a `menu` must contain `menuitem`, `menuitemcheckbox`, or `menuitemradio` elements. Missing required children breaks the accessibility tree and prevents assistive technologies from correctly interpreting the interface.

Elements with ARIA Roles Must Have Required Parent

Certain ARIA roles can only be used as children of specific parent roles. For example, `option` must be contained in a `listbox` or `combobox`, `tab` must be in a `tablist`, and `menuitem` must be in a `menu` or `menubar`. Using these child roles without their required parent roles breaks the accessibility tree and prevents assistive technologies from correctly interpreting the widget structure.

ARIA roles must be valid

An element has an invalid or non-existent ARIA role. Assistive technologies cannot interpret invalid roles, leading to broken accessibility.

ARIA roles must conform to valid values

An ARIA attribute has an invalid value. Screen readers and assistive technologies cannot interpret invalid ARIA values, breaking accessibility features.

ARIA Attributes Must Be Valid

ARIA (Accessible Rich Internet Applications) attributes used in HTML elements must be valid attributes that are defined in the ARIA specification. Using invalid or misspelled ARIA attributes can cause assistive technologies to ignore or misinterpret the intended accessibility information.

Forms & Inputs

5 rules

1.3.5 Identify Input Purpose

Autocomplete attribute values must be valid

Form fields use invalid or unsupported `autocomplete` tokens.

Buttons must have discernible text

A button element does not have text content or accessible text. Screen reader users cannot understand the button's purpose.

Input buttons must have discernible text

An `<input>` element with `type="button"`, `type="submit"`, or `type="reset"` does not have discernible text. Screen reader users cannot understand the button's purpose.

Image input buttons must have alternate text

`<input type="image">` elements are missing meaningful `alt` text.

Form elements must have labels

Form input elements do not have associated labels. Screen reader users cannot determine what information to enter into form fields, and all users lose the benefit of clickable labels.

Images & Media

6 rules

Image map area elements must have alternate text

`<area>` elements inside image maps are missing meaningful `alt` text.

1.2.1 Audio-only and Video-only

Audio-only content must provide a transcript

Audio-only media is presented without an equivalent text transcript.

Frames must have a title attribute

An `<iframe>` or `<frame>` element does not have a `title` attribute, or the title is empty. Screen reader users cannot understand the frame's purpose without a descriptive title.

Images must have alternate text

Images do not have alternative text (alt attributes). Screen reader users cannot access the information conveyed by images, and if the image fails to load, all users lose context.

Object elements must have text alternatives

An `<object>` element is missing equivalent text content or fallback information.

`<video>` elements must have captions

A `<video>` element with audio lacks captions. Deaf and hard-of-hearing users cannot access the audio content.

1.2.2 Captions

Document Structure

7 rules

Documents must have a title element

The document does not have a `<title>` element in the `<head>`, or the title is empty. Users need page titles to identify and navigate between pages.

2.4.2 Page Titled

IDs must be unique

Two or more elements on the page have the same `id` attribute value. Duplicate IDs break assistive technologies, form labels, ARIA relationships, and JavaScript functionality.

4.1.1 Parsing

2.4.6 Headings and Labels

Headings must have discernible text

A heading element (h1-h6 or role="heading") is empty or has no accessible text. Empty headings confuse screen reader users and break document structure.

Heading levels should only increase by one

Heading levels skip one or more levels (e.g., jumping from `<h1>` to `<h3>`, skipping `<h2>`). This breaks the document outline and confuses screen reader users navigating by headings.

HTML element must have a lang attribute

The `<html>` element does not have a `lang` attribute. Screen readers and assistive technologies need this to pronounce content correctly and apply appropriate language-specific rules.

3.1.1 Language of Page

html element must have a valid lang attribute value

The `<html>` element has a `lang` attribute with an invalid value. Screen readers and browsers cannot determine the correct language for pronunciation and processing.

3.1.1 Language of Page

Page must have a level-one heading

The page does not contain a level-one heading (`<h1>`). Screen reader users rely on heading structure to understand page content and navigate efficiently.

Lists & Landmarks

6 rules

Definition lists must only contain dt and dd elements

A `<dl>` contains invalid direct children that are not `<dt>`, `<dd>`, `<script>`, or `<template>`.

Definition list items must be inside a definition list

`<dt>` or `<dd>` elements are used outside a `<dl>` container.

Page must contain a level-one heading

The page does not have exactly one `<main>` landmark or `role="main"` element. Users need a main landmark to skip directly to the main content and understand page structure.

`<ul>` and `<ol>` must only directly contain `<li>`, `<script>` or `<template>` elements

A `<ul>` or `<ol>` element contains children other than `<li>`, `<script>`, or `<template>` elements. This breaks the semantic list structure and confuses screen readers.

`<li>` elements must be contained in a `<ul>` or `<ol>`

An `<li>` element exists outside of a `<ul>`, `<ol>`, or `<menu>` element. This breaks semantic list structure and confuses screen readers.

All page content should be contained by landmarks

Important page content is not grouped inside landmark regions (`main`, `nav`, `header`, `footer`, `aside`, `section` with accessible name).