# Accessibility

> Check that pages are usable whatever the abilities of the people who use them. It builds on the `web-core` pack.

Source: https://axx.nimbusxr.us/references/packs/web-a11y/

Check that pages are usable whatever the abilities of the people who use them. It builds on the `web-core` pack.

- **Audits.** `the page has no accessibility violations` audits the page with [axe-core](https://github.com/dequelabs/axe-core), the accessibility engine of Deque that Lighthouse runs too, against the WCAG 2.1 AA rules by default: fields without labels, text without enough contrast, images without alternative text... The pack downloads axe-core 4.13.0 the first time. A violation fails the step, which says which rule, how serious, and which elements.
- **Structure.** `the page's accessible structure is:` checks what assistive technology reads: the headings, fields, buttons and texts, and their names, as Playwright's ARIA snapshots describe them. List what matters; the rest of the page may be anything.

```yaml
packs:
  web-a11y:
    standard: wcag21aa     # wcag2a, wcag2aa, wcag21a, wcag21aa or wcag22aa
    ignore: [region]       # rules to leave out, by their axe-core id
```

Add it to a project with `axx pack add web-a11y`; it builds on [`web-core`](https://axx.nimbusxr.us/references/packs/web-core/), which comes with it.

## Settings

In `axx.yaml`, under `packs.web-a11y`:

| Setting | Takes | Values | Default |
|---|---|---|---|
| `ignore` | Rules the audits leave out, by their axe-core id, like color-contrast. | a list of text | |
| `standard` | The WCAG level pages are audited against. | `wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa`, `wcag22aa` | `wcag21aa` |

## Steps

### `web-a11y.page`

```gherkin
Then the page has no accessibility violations
```

Audit the page, in every frame, with axe-core against the WCAG rules of `packs.web-a11y.standard` (2.1 AA by default): the step fails with each rule violated, how serious it is, and the elements that violate it.

**Example:**

```gherkin
Then the page has no accessibility violations
```

_Since 0.1.1._

### `web-a11y.element`

```gherkin
Then the {string} {element} has no accessibility violations
```

Audit one part of the page, by its name or a selector, with axe-core, as `the page has no accessibility violations` does.

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{string}` | text in double or single quotes, which the step leaves out |  | `"Get a quote"`, `'Express'` |
| `{element}` | a kind of element on the page, plural after a number (`buttons`): a `field` by its label or placeholder, an `option` is a radio button, an `element` is anything, by its text, label, alternative text or title | `button`, `field`, `checkbox`, `option`, `link`, `tab`, `menu item`, `element` | `button`, `field` |

**Example:**

```gherkin
Then the "css=form" element has no accessibility violations
```

_Since 0.1.1._

### `web-a11y.structure`

```gherkin
Then [[within {duration} ]]the page's accessible structure is:
  """
  ...
  """
```

Check what assistive technology reads on the page, in Playwright's ARIA snapshot format.

- A line is a role and a name, like `- heading "Get a quote" [level=1]` or `- button "Get a quote"`, nested for what is inside.
- Only what is listed is checked, in its order.
- A name between slashes is a regular expression.
- The check waits for the page to match: 10 seconds, or `within {duration}`.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |

**Variants**, the parts in `[[...]]` said or left out:

- `the page's accessible structure is:`
- `within {duration} the page's accessible structure is:`

**Example:**

```gherkin
Then the page's accessible structure is:
```

_Since 0.1.1._

### `web-a11y.element.structure`

```gherkin
Then [[within {duration} ]]the {string} {element}'s accessible structure is:
  """
  ...
  """
```

Check what assistive technology reads in one part of the page, by its name or a selector, as `the page's accessible structure is:` does.

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) |  | `5s`, `2m` |
| `{string}` | text in double or single quotes, which the step leaves out |  | `"Get a quote"`, `'Express'` |
| `{element}` | a kind of element on the page, plural after a number (`buttons`): a `field` by its label or placeholder, an `option` is a radio button, an `element` is anything, by its text, label, alternative text or title | `button`, `field`, `checkbox`, `option`, `link`, `tab`, `menu item`, `element` | `button`, `field` |

**Variants**, the parts in `[[...]]` said or left out:

- `the {string} {element}'s accessible structure is:`
- `within {duration} the {string} {element}'s accessible structure is:`

**Example:**

```gherkin
Then the "css=form" element's accessible structure is:
```

_Since 0.1.1._