a11y - the accessibility CLI for Node

A11y Command-line Tools

Web accessibility audits powered by the Chrome Accessibility Developer Tools.


Accessible web sites need to work across multiple devices with varying screen-sizes and different kinds of input. Moreover, sites should be usable by the broadest group of users, including those with disabilities. When designing for accessibility, there are four key areas of disability to consider: visual, hearing, mobility and cognition.

The A11y Command-line Tools assist in discovering common web accessibility issues, such as detecting if your page can be read with a screenreader or works well with high-constrast mode enabled. Whilst it not possible to automate the detection of 100% of accessibility issues, the A11y CLI can help catch and improve your accessibiltiy baseline significantly.

Audit accessibility issues in your web pages

Run audits against local or remote URLs to return a list of accessibility improvements that can be made. We even point out the DOM elements responsible.

a11y bbc.co.uk 
These elements are focusable but either invisible or obscured by another element #h4weather > .state-container > .forecasts > .forecast:nth-of-type(2) > .weather-icon > A #h4weather > .state-container > .forecasts > .forecast:nth-of-type(3) > .weather-icon > A Text elements should have a reasonable contrast ratio #h4weather > .state-container > H2 Meaningful images should not be used in element backgrounds #orb-nav-more > A > .orb-icon.orb-icon-arrow ...

Enforce an accessible baseline

A baseline success report will indicate when you've passed our accessibility tests. Green ticks all around!

#orb-nav-more > A > .orb-icon.orb-icon-arrow

 Elements with ARIA roles must use a valid, non-abstract ARIA role
 Controls and media elements should have labels
 Images should have an alt attribute
 The purpose of each link should be clear from the link text
 The web page should have a title that describes topic or purpose
 Elements with ARIA roles must have all required attributes for that role


You will need Node.js in order to install and use a11y on your machine. Once installed, run the follwing one-liner at the command-line:

npm install -g a11y

PhantomJS, which is used for generating the screenshots, is installed automagically, but in some rare cases it might fail to and you'll get an Error: spawn EACCES error. Download PhantomJS manually and reinstall a11y if that happens.


Run an audit against a single URL:

a11y todomvc.com

or multiple URLs:

a11y todomvc.com https://google.com 
.... https://google.com


Query help

a11y --help

Customise viewport size

a11y --viewport-size=800x600

Write audit to file

a11y url > audit.txt

Module Usage


a11y(URL, callback) accepts a string as input and takes a callback providing a reports object with the accessibility audit for the supplied URL.


Audit a remote URL and generate an accessibility report:

var a11y = require('a11y');

a11y('twitter.com', function (err, reports) {
    var output = JSON.parse(reports);
    var audit = output.audit; // a11y Formatted report
    var report = output.report; // DevTools Accessibility Audit formatted report

Work with the output of reports.audit:

var a11y = require('a11y');

a11y('twitter.com', function (err, reports) {
    reports.audit.forEach(function (el) {
        // result will be PASS, FAIL or NA
        if (el.result === 'FAIL') {
            // el.heading
            // el.severity
            // el.elements
For even more granular control, the Chrome Accessibility Developer Tools can now be installed from npm.


Projects building on this module


If you're new to Web Accessibility and would like to learn more about improving the accessibility of your pages, the following resources may prove useful: