DEV Community: Sandi Barr

Angular ESLint Rules for Accessible HTML Content

Sandi Barr — Tue, 10 Jan 2023 19:14:04 +0000

Content accessibility for built-in HTML elements is the third and final category in this series on Angular ESLint accessibility rules. These rules validate several HTML attributes that developers commonly overlook regarding accessibility. They check for alt text on images, accessible content in buttons, links, and headings, and proper form labels and table header associations. Angular ESLint accessibility rules provide immediate guidance on accessibility best practices right in the code, resulting in more accessible and user-friendly Angular applications.

The Rules

Previous articles in this series discussed how to add Angular ESLint and configure these rules in .eslintrc.json config files, so let's get straight into the rules:

Alt Text

@angular-eslint/template/accessibility-alt-text
Elements Have Content

@angular-eslint/template/accessibility-elements-content
Label Has Associated Control

@angular-eslint/template/accessibility-label-has-associated-control
Table Scope

@angular-eslint/template/accessibility-table-scope
No Distracting Elements

@angular-eslint/template/no-distracting-elements
Button Has Type

@angular-eslint/template/button-has-type

Rule: Alt Text

@angular-eslint/template/accessibility-alt-text

The accessibility-alt-text rule validates that all images have alternative text. Images must have an alt attribute to meet WCAG 2.1 Success Criterion 1.1.1: Non-text Content that states all non-text content should have a text alternative that serves the equivalent purpose.

Follow these guidelines for providing meaningful and concise alt text:

Alt text should express the relevant detail in an image to stand in for the same purpose, meaning, and intent.
Alt text should not be redundant or repeat information from the image caption.
Alt text should be short and to the point, ideally 150 characters or less.

When there is no alt attribute on an <img>, some screen readers will announce the image src instead. Including an empty alt attribute for decorative images indicates to screen readers that these images do not convey additional meaning or information:

<img alt="" src="decorative.gif">

In addition to checking for the alt attribute on <img> elements, the accessibility-alt-text rule also validates <input type="image">, <area>, and <object> elements, which support these attributes as alternative text:

HTML element	alternative text attributes
`<img>`	`alt`
`<input type="image">`	`alt`, `aria-label`, `aria-labelledby`
`<area>`	`alt`, `aria-label`, `aria-labelledby`
`<object>`	`aria-label`, `aria-labelledby`, `title`

Rule: Elements Have Content

@angular-eslint/template/accessibility-elements-content

The accessibility-elements-content rule ensures that <a>, <button>, and <h1> - <h6> elements have content. Screen readers announce these elements by their role and name (and level for headings.) Links, buttons, and headings are semantic elements with inherent meaning and implicit roles, and the accessible name for these elements comes from their content, title, or aria-label.

A button, link, or heading name may also come from a child element with plain text content, a title, or aria-label. Don't add redundant and unnecessary aria-labels where the accessible name comes from a child element. Use the Accessibility pane in Chrome DevTools to inspect an element's computed name:

Rule: Label Has Associated Control

@angular-eslint/template/accessibility-label-has-associated-control

The HTML <label> element gives an accessible name to form controls. Labels are important for helping users understand the purpose of <input>, <select>, <textarea>, <output>, <meter>, and <progress> elements.

A control can have more than one <label>.
A <label> cannot be associated with more than one control.
Do not use <label> independently without an associated control.

A <label> is associated with a form control with either an implicit or explicit association, and both styles are widely supported. Nesting a control inside <label> creates an implicit association between the label and control:

<label>
  <input type="checkbox">
  Blue
</label>

Whereas, assigning an id to the control and using a matching for attribute on the <label> creates an explicit association:

<label for="city">City</label>
<input id="city" type="text">

The accessibility-label-has-associated-control rule determines if a label has an implicit association with a control nested inside the label or if the label has the for attribute. The rule does not look elsewhere in the template for a control with an id matching the label's for attribute and does not validate explicit label and control pairings. This is a natural limitation of static code analysis tools like Angular ESLint, so you’ll want to use additional testing techniques to validate the compiled application. The for attribute could be a bound value, and Angular ESLint template rules do not validate bound values. Rules are generally limited to validating individual template nodes and their children, and the control could even be in another component's template separate from the label.

Configuration Options for Label Has Associated Control

The accessibility-label-has-associated-control rule supports the configuration options labelComponents and controlComponents. The labelComponents option adds validation for custom label components. The controlComponents option configures the rule to recognize an implicit association on custom controls nested inside a label.

Option: Custom Label Components

Configure "labelComponents" for "my-custom-label" with "forControl":

"@angular-eslint/template/accessibility-label-has-associated-control": [
  "error",
  {
    "labelComponents": [
      {
        "selector": "my-custom-label",
        "inputs": ["forControl"]
      }
    ]
  }
]

Validation on a custom label component to either require the forControl input or to have a nested control:

<my-custom-label forControl="myId">
  Custom
</my-custom-label>
<input id="myId" type="text"/>

<my-custom-label>
  Custom
  <input type="text"/>
</my-custom-label>

Option: Custom Control Components

Configure "controlComponents" for "my-custom-control":

"@angular-eslint/template/accessibility-label-has-associated-control": [
  "error",
  {
    "controlComponents": ["my-custom-control"]
  }
]

Validation on a custom control nested inside a label with an implicit association:

<label>
  Custom
  <my-custom-control></my-custom-control>
</label>

Rule: Table Scope

@angular-eslint/template/accessibility-table-scope

The accessibility-table-scope rule validates the scope attribute for table headers. The scope attribute specifies which cells belong with a table header (<th>.) Table header scope accepts the following values:

row: associates a table header with all the cells in that row.
col: associates a table header with all the cells in that column.
rowgroup: associates a table header that spans multiple rows with all the cells in that row group.
colgroup: associates a table header that spans multiple columns with all the cells in that column group.

When table header scope is not specified, browsers and assistive technologies infer the relationship between table headers and their cells. Tables with headers in a single row or column do not need the scope attribute. More complex tables with irregular, multi-level, or both row and column headers should explicitly define which cells belong to which headers by using the scope attribute on their table headers or the id attribute on table headers with the headers attribute on table cells.

Rule: No Distracting Elements

@angular-eslint/template/no-distracting-elements

The no-distracting-elements rule disallows usage of the <blink> and <marquee> elements, which are both deprecated and no longer recommended for use.

The <blink> element is more than distracting. Flashing content can trigger seizures in people with photosensitive epilepsy. WCAG 2.1 Success Criterion 2.3.1 dictates that there are no more than three flashes in a one second period or that the flash is below the threshold.

The scrolling content in a <marquee> element can create barriers for anyone who struggles with moving objects or people with cognitive disabilities like attention deficit disorder. WCAG 2.1 Success Criterion 2.2.2 states that users must be able to stop or hide any moving, blinking, scrolling, or auto-updating information.

Bonus Rule: Button Has Type

@angular-eslint/template/button-has-type

I mention this last rule as a bonus because it is not specifically an accessibility rule but is commonly missed and can lead to surprising functionality. The button-has-type rule checks for the type attribute on HTML <button> elements. A <button> inside a <form> without a type acts as a submit button and submits the form when pressed:

<form>
  <label><input type="checkbox">Yes</label>

  <button>Submits the Form</button>

  <button type="button">Not a Submit</button>

  <button type="reset">Resets the Form</button>

  <button type="submit">Submits the Form</button>
</form>

That's All, Folks!

The Angular ESLint rules covered in this series enable developers to create more accessible and user-friendly Angular applications by helping to ensure keyboard accessibility, ARIA compliance, and accessible HTML content. The first article discusses rules for ensuring that all interactive elements are reachable with a keyboard and that focus is not improperly managed. The second article discusses Angular ESLint rules to check that ARIA roles have the required attributes and that ARIA attributes are valid. This third and final article discusses Angular ESLint rules to ensure accessible HTML content, such as image alt text, accessible names for form controls, buttons, links, and headings, and table heading scope. That covers all the rules pertaining to accessibility available with Angular ESLint.

Static code analysis with Angular ESLint has the advantage of identifying issues early in development, but performing further automated and manual browser-based testing is essential for ensuring full accessibility. These Angular ESLint accessibility rules inspect individual nodes and elements used in the template code. It is also important to validate accessibility within the context of the entire application to check that headings are properly nested, that there are no nested interactive controls, that landmarks like <header>, <aside>, <nav>, and <main> are used and labeled correctly, etc. Incorporating accessibility testing into each stage of the development and release process ensures that our Angular applications are usable by a wide range of users, including those with disabilities.

Recommended Testing Tools and Libraries:

References:

Understanding SC 1.1.1:Non-text Content (Level A) on W3C's Understanding WCAG 2.1
Decorative Images on W3C Web Accessibility Initiative
Providing Accessible Names and Description on W3C Web Accessibility Initiative ARIA Authoring Practices Guide
Tables Tutorial on W3C Web Accessibility Initiative
Understanding SC 2.3.1:Three Flashes or Below Threshold (Level A) on W3C's Understanding WCAG 2.1
Understanding SC 2.2.2:Pause, Stop, Hide (Level A) on W3C's Understanding WCAG 2.1

Angular ESLint Rules for ARIA

Sandi Barr — Mon, 14 Nov 2022 15:16:34 +0000

The acronym ARIA stands for Accessible Rich Internet Applications. The purpose of ARIA is to make web content more accessible for people with disabilities. ARIA can enhance accessibility in custom-designed user interface controls and components, but incorrect use of ARIA can hinder accessibility and create a worse experience than no ARIA at all. Standard, semantic HTML components don't need ARIA to be accessible. As the saying goes, no ARIA is better than bad ARIA.

Advanced use of ARIA is a specific discipline that should be encapsulated into custom UI components that are used to create a consistent experience across an application. Creating such a reusable component library is a common practice in Angular development. Angular ESLint has rules for checking ARIA, but Angular does not add this validation out of the box. This post walks you through how to add Angular ESLint to a component library project, then dives deeper into the ARIA rules. I'll cover what each rule looks for in the Angular template code and how it uses the underlying libraries to validate ARIA roles and attributes.

Add Angular ESLint to an Angular Library Project

In the previous post I covered how to add Angular ESLint to an Angular project. This post shows how to create an Angular library project with Angular ESLint support.

To generate a new Angular workspace run the ng new schematic without creating the default application:

ng new my-workspace --create-application false
cd my-workspace

Add Angular ESLint to the workspace with the ng add schematic:

ng add @angular-eslint/schematics

Generate an Angular library using Angular ESLint's library schematic that runs the Angular library schematic under the hood then adds support for Angular ESLint:

ng generate @angular-eslint/schematics:lib

The workspace will have both root and project level eslint configuration. The project .eslintrc.json files extend from the root level config, so rules and their options can be set at the global level and added or overridden at the project level. Configure the ARIA template rules under "*.html" overrides:

Root and project level .eslintrc.json config

Next let's take a deeper look at the two ARIA rules from Angular ESLint that are configured in the .eslintrc.json above:

Valid ARIA

@angular-eslint/template/accessibility-valid-aria
Role Has Required ARIA

@angular-eslint/template/accessibility-role-has-required-aria

Angular ESLint ARIA Rules

The Angular ESLint ARIA rules run against Angular template code both inline and in separate template files and identify incorrect usage of WAI-ARIA roles and their associated ARIA attributes. Ensuring WAI-ARIA criteria are met enables user agents and assistive technologies to gather information about and interact with web content and controls.

These rules originated from the eslint-plugin-jsx-a11y project and were ported over and implemented for Angular ESLint. Angular ESLint and eslint-plugin-jsx-a11y both use the aria-query and axobject-query libraries to query information about ARIA roles and attributes.

Rule: Valid ARIA

`@angular-eslint/template/accessibility-valid-aria`

The accessibility-valid-aria rule checks aria-* attributes to be valid ARIA. The rule looks for HTML elements with bound or plain text ARIA attributes. Then it looks up the ARIA property definition from the aria-query library to get the ARIA attribute value type and allowed values.

If aria-query doesn’t have a definition for the matched ARIA attribute, the rule reports an invalid attribute value violation with the suggested fix to remove it:

Violation of rule @angular-eslint/template/accessibility-valid-aria: The aria-control is an invalid ARIA attribute

If the ARIA attribute value is a literal value, it checks the value to be of the defined value type and one of the allowed values if provided. If the ARIA attribute value doesn’t match the ARIA property definition, the rule reports a violation that the attribute’s value is invalid:

Violation of rule @angular-eslint/template/accessibility-valid-aria: The aria-valuenow has an invalid value

The template parser can only check the nodes and static values in the template itself, so a dynamically bound attribute value does not get flagged as a violation:

No violation on bound attribute value

Rule: Role Has Required ARIA

`@angular-eslint/template/accessibility-role-has-required-aria`

Note: You must be on at least version 14.2.0 of Angular ESLint to use the accessibility-role-has-required-aria rule.

This rule matches HTML elements with a plain text role attribute and checks that the given role has the required ARIA attributes using the role definition from the aria-query library. For example, the switch role definition has one required property, aria-checked.

Using role mappings from the axobject-query library, it determines if the HTML element's semantic role matches the given role. The role="switch" can be applied to an <input type="checkbox"/> and the required aria-checked property is covered by the element’s semantic role. A <span> element does not have those same semantic properties and would be flagged as a violation if given the role="switch" without aria-checked:

Violation of rule @angular-eslint/template/accessibility-role-has-required-aria: The span with role="switch" does not have required ARIA properties: aria-checked

The complete set of roles with required ARIA properties covered by the accessibility-role-has-required-aria rule is as follows:

WAI-ARIA role	Required ARIA
checkbox	aria-checked
menuitemcheckbox	aria-checked
menuitemradio	aria-checked
radio	aria-checked
switch	aria-checked

heading	aria-level

option	aria-selected
treeitem	aria-selected

combobox	aria-controls aria-expanded

meter	aria-valuenow
slider	aria-valuenow

scrollbar	aria-controls aria-valuenow

Suggestion for Adoption

Enabling Angular ESLint's accessibility rules all at once in a codebase with existing accessibility issues can produce a long list of violations that might initially seem overwhelming and difficult to prioritize. Enable these sets of rules incrementally to tackle one category at a time:

Keyboard Accessibility
All content and functionality must be usable with the keyboard. Keyboard access is essential for assistive technologies and should be a top priority. The article in this series on Angular ESLint Rules for Keyboard Accessibility covers the lint rules that can help. You won't be able to automate validation of all keyboard functionality with lint rules or automated testing. Be sure to incorporate manual interaction testing into your process to ensure a logical focus order is maintained along with a visible focus ring.
ARIA Roles and Attributes
Providing accessible components from a shared library helps standardize your approach to UI/UX and accessibility across your application(s). Isolate most ARIA to your custom UI components and use Angular ESLint's ARIA rules to validate best practices.
Content and Relationships
These rules ensure accessibility for non-text content and content relationships in forms and tables. Alternative text should convey the purpose and context for non-text content. Ensuring content accessibility also requires human input and manual review to make sure the content is meaningful and presented consistently. Stay tuned for my last article in this series about the Angular ESLint Accessibility Rules for Content and Relationships.

But Wait, There's More? There Sure Could Be

The eslint-plugin-jsx-a11y library, where these Angular ESLint ARIA rules originate, has even more rules for validating ARIA that could be borrowed from and added to Angular ESLint. These rule additions could also leverage aria-query and axobject-query to validate ARIA usage and encourage better practices with semantic HTML.

Even More ARIA Rules in eslint-plugin-jsx-a11y

I would also like to implement these rules for Angular ESLint:

aria-role

Elements with ARIA roles must use a valid, non-abstract ARIA role.
Valid ARIA roles must be used in order for user agents to understand and interact with those elements according to specifications. Abstract roles are the foundational roles upon which other WAI-ARIA roles are built and organized and are not to be used directly.
role-supports-aria-props

Enforce that elements with explicit or implicit roles defined contain only aria-* properties supported by that role.
It does no good to add ARIA attributes to elements with roles that don't support those attributes.
no-aria-hidden-on-focusable

Enforce that aria-hidden="true" is not set on focusable elements.
Using aria-hidden hides an element and its children from the accessibility API. Elements that aren't accessible to assistive technologies should not be able to receive focus via keyboard.
no-interactive-element-to-noninteractive-role

ARIA roles should not be used to convert an interactive element to a non-interactive element.
This rule prevents interactive elements meant as controls from being assigned non-interactive roles meant for content or containers. A content role such as meter, for example, could not be assigned to an <input> or <button> element.
no-noninteractive-element-to-interactive-role

ARIA roles should not be used to convert a non-interactive element to an interactive element.
Elements meant for content or containers, such as <main>, <h1>, and <li>, should not be assigned interactive roles meant for controls such as the button or checkbox roles.
no-redundant-roles

ARIA roles should not redundantly match an element's default/implicit role already set by the browser.
An <input type="checkbox"> element already has the implicit role checkbox, so adding role="checkbox" would be redundant.
prefer-tag-over-role

Enforces using semantic DOM elements over the ARIA role property.
This rule prevents content or container elements like <span> or <div> from being assigned roles like banner or heading where a built-in, semantic HTML element is preferable.

🎉 Shout out in the comments if you think having these rules in Angular ESLint would improve accessibility practices in your Angular codebase!

References:

ARIA Authoring Practices Guide on W3C Web Accessibility Initiative
Easy Checks – A First Review of Web Accessibility on W3C Web Accessibility Initiative
WAI-ARIA roles on MDN
Understanding Success Criterion 4.1.2: Name, Role, Value on W3C's Understanding WCAG 2.1
eslint-plugin-jsx-a11y on GitHub
aria-query on GitHub
axobject-query on GitHub

Angular ESLint Rules for Keyboard Accessibility

Sandi Barr — Fri, 14 Oct 2022 13:20:22 +0000

When using built-in HTML elements, the browser provides proper and expected keyboard support out of the box. Users can tab to a form input, use arrow keys to navigate through options in a select, or press a button with the Spacebar or Enter key. The recommended practice is to use semantic HTML elements and rely on the browser's built-in affordances for keyboard accessibility. Still, this advice is frequently not followed in favor of custom designed elements. Instead of using a button, developers sometimes add a click event to a span or div without realizing their implementation is not accessible to keyboard users. Ensuring accessible keyboard navigation also enables users of assistive technologies like switch devices to interact with your application. Angular ESLint's accessibility rules can catch some of these common keyboard navigation pitfalls and provide helpful and immediate feedback on Angular template code both inline and in separate template files.

How to Get Angular ESLint

If you're not already using Angular ESLint, you can add it to an Angular project by running the schematic:

ng add @angular-eslint/schematics

The schematic adds a target to angular.json that enables the lint command on the project:

ng lint

Configure the rules in the .eslintrc.json file under "*.html" overrides:

ESLint template rule configuration in .eslintrc.json

Read on to learn more about the accessibility guidelines and best practices behind each of these rules.

Rules for Accessible Keyboard Navigation

No Positive Tab Index

`@angular-eslint/template/no-positive-tabindex`

WCAG Success Criterion 2.4.3 Focus Order dictates that elements on the page should receive focus in a sequential order that is meaningful to the content. The tab order should flow through the page from the header and navigation, through the main content, end at the footer, and circle back around. Built-in HTML elements that support interactive behaviors can be navigated to and receive focus by tabbing through the page.

Generally, the tabindex attribute isn't needed for buttons, links, and form controls. Assigning tabindex adds focus support to an element that can't otherwise receive focus. A tabindex greater than zero inserts elements into the focus order before elements without a tabindex or a tabindex of zero. A tabindex of -1 is a particular case that takes elements out of the focus order but allows them to receive focus programmatically. Enable the no-positive-tabindex rule to prevent usage of tabindex values other than 0 or -1.

No Autofocus

`@angular-eslint/template/no-autofocus`

The no-autofocus rule discourages use of the autofocus attribute. Using autofocus can cause screen readers to jump to a control without context and break the expected tab navigation flow.

Mouse Events Have Key Events

`@angular-eslint/template/mouse-events-have-key-events`

All content must be accessible with the keyboard alone. For example, if mousing over an element reveals additional content, there should be consideration for keyboard users who may navigate via tab to focus the trigger. The mouse-events-have-key-events rule ensures that elements with (mouseover) or (mouseout) event handlers also have corresponding keyboard support with (focus) or (blur). Enabling this rule assists with following the WCAG technique SCR2: Using redundant keyboard and mouse event handlers

Click Events Have Key Events

`@angular-eslint/template/click-events-have-key-events`

Wherever users can click, they should also be able to access via keyboard. The click-events-have-key-events rule ensures that elements with (click) event handlers also have at least one accompanying keyboard event, meaning (keyup), (keydown), (keypress), or a key filtered variation like (keyup.enter).

A click-events-have-key-events eslint rule violation appears when developers use a (click) event on an element that is not interactive by default and does not have built-in keyboard accessibility. For example, adding (click) to a <span> or a <div> to act like a button is not a button. A <button> does not need key events added because the browser triggers the click event with the Spacebar or Enter key.

Anchor elements (<a>) with (click) events that don't have an href or routerLink also violate this rule. Anchor links must include the href attribute for built-in accessibility and keyboard support. If an <a> has (click) and no href, should it instead be a <button>? Links and buttons are semantically different. Buttons are meant to do something within the view; whereas, links are for navigation to a different view or page (one exception being download links.)

Here's what this rule violation looks like with the ESLint extension enabled in VS Code:

Violation of rule @angular-eslint/template/click-events-have-key-events: click must be accompanied by either keyup, keydown or keypress event for accessibility.

Another thing to consider is that key event handlers on an element can only be triggered when that element has focus. When used on its own, the click-events-have-key-events rule could encourage developers to add a key event to elements that do not have native keyboard support and may not actually receive focus via tabbing. How do we confirm these custom elements we intend to work with both the mouse and keyboard can also receive focus?

interactive-supports-focus enters the chat...

Accessibility Interactive Supports Focus

`@angular-eslint/template/accessibility-interactive-supports-focus`

Note: You must be on at least version 14.2.0 of Angular ESLint to use the accessibility-interactive-supports-focus rule.

The intent of accessibility-interactive-supports-focus is to verify that HTML elements with interaction handlers (click, keydown, keyup, keypress) can receive focus either because the element is interactive by default (like a <button>, <input>, <select>, etc.) or by adding a tabindex to the element. When using tabindex, you'll also want to check your templates against that no-positive-tabindex rule mentioned previously. These keyboard navigation rules work in conjunction with each other to facilitate the development of accessible web applications.

Part of a "Complete Breakfast"

Applying these rules with Angular ESLint can give developers immediate feedback on their template code and identify problems early in development. However, the lint checks are limited to the precompiled template nodes and static values. These template rules only apply to what's in the template, so they also cannot check Angular Component host properties or HostBindings for bound attributes. Browser-based testing tools that run against compiled application code do a more thorough evaluation by validating elements in relationship to each other and within the entire page. Use a combination of automated and manual accessibility testing alongside Angular ESLint for more thorough accessibility checks on your Angular applications.

Stay tuned for my next post on Angular ESLint Rules for ARIA (Accessible Rich Internet Applications)

References:

Keyboard Accessibility on WebAIM
Assistive Technologies – The Switch on Axess Lab
WCAG Success Criterion 2.4.3 Focus Order on W3C's Understanding WCAG 2.1
SCR2: Using redundant keyboard and mouse event handlers on W3C's Techniques for WCAG 2.1
Links vs. Buttons in Modern Web Applications on MarcySutton.com