Adding accessibility linting to Angular projects

Accessibility matters for every web application. The World Health Report estimates that roughly 15% of the global population—over a billion people—live with some form of disability, so building interfaces that everyone can use is an essential part of development. For Angular developers, the codelyzer tool makes it possible to catch accessibility issues while you code rather than after deployment.

What codelyzer checks

codelyzer runs on top of TSLint and is included by default when you create a project with the Angular CLI. It offers over 50 linting rules for Angular TypeScript projects, around 10 of which are dedicated to accessibility criteria. The New Accessibility rules in Codelyzer article covers each rule and the reasoning behind it.

These accessibility rules are experimental and off by default. You can enable them by adding them to your project’s tslint.json configuration file:

{
  "rulesDirectory": [
    "codelyzer"
  ],
  "rules": {
    ...,
    "template-accessibility-alt-text": true,
    "template-accessibility-elements-content": true,
    "template-accessibility-label-for": true,
    "template-accessibility-tabindex-no-positive": true,
    "template-accessibility-table-scope": true,
    "template-accessibility-valid-aria": true,
    "template-click-events-have-key-events": true,
    "template-mouse-events-have-key-events": true,
    "template-no-autofocus": true,
    "template-no-distracting-elements": true
  }
}

Getting feedback as you code

TSLint integrates with most popular editors and IDEs. If you use VS Code, install the TSLint plugin. WebStorm comes with TSLint support built in, and for other editors you can check the TSLint README. With the accessibility rules configured, errors surface as popups for TypeScript files and inline templates directly in your editor:

A screenshot of a codelyzer popup in a text editor.
A codelyzer popup showing a form element labeling error.

For a full-project audit that includes external templates, run ng lint from the command line:

Linting with Angular CLI

Static analysis versus runtime checks

Lighthouse is a complementary option for accessibility enforcement. The main distinction between the two tools is when they run. Codelyzer performs static analysis at development time without executing your application, giving you immediate feedback in the editor or terminal. Lighthouse, on the other hand, loads and runs the app before performing its checks via dynamic analysis.

Both fit naturally into a development workflow. Lighthouse provides broader audit coverage, while codelyzer offers quicker iteration with constant inline feedback.

Bringing checks into CI

You can also enforce accessibility rules in your continuous integration pipeline. Running ng lint on every code change—each pull request, for example—means your CI flags accessibility violations before the code ever reaches review.

Summary

  1. Turn on codelyzer’s experimental accessibility rules in your TSLint config.
  2. Run ng lint to audit the whole project, including external templates.
  3. Resolve all accessibility violations the tool reports.
  4. Add Lighthouse audits when you want runtime accessibility checking.