WCAGify

WCAGify is a simple function for people who need to reference the Web Content Accessibility Guidelines frequently and are tired of copying and pasting.

WCAGify looks up WCAG 2.2 criteria based on a reference number supplied as a string and returns an object with the URL and name etc. It means you don't have to get the criterion name 100% correct as long as you know the reference number. It also adds consistency to your reports by returning the name exactly as it's formatted in the WCAG 2.2 standard.

Usage

Install WCAGify:

npm install wcagify

Require WCAGify:

const wcagify = require('wcagify')

In the following examples, all the function calls would return the same object.

// Look up by reference number
wcagify('1.1.1 Non-text Content')
wcagify('1.1.1 nontext content')
wcagify('1.1.1')
wcagify('1.1.1 Potato')

// Or look up by name alone - case, punctuation and small typos are forgiven
wcagify('Non-text Content')
wcagify('non text content')
wcagify('non-text contnet')

// Return object
{
  criterion: '1.1.1 Non-text Content',
  ref: '1.1.1',
  name: 'Non-text Content',
  link: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html',
  level: 'A',
  impacts: ['Auditory', 'Visual', 'Cognitive']
}

If a string contains both a reference number and a name, the reference number wins. A name-only lookup that could match more than one criterion equally well (for example 'contrast') throws an error rather than guessing.

If you would rather branch on the result than catch errors - handy inside templates - use wcagify.safe, which returns null on a miss instead of throwing:

const reference = wcagify.safe(userInput)
if (reference) { /* use reference.link */ }

WCAG 2.1

If you audit against WCAG 2.1, pass a version option and links, names and levels follow the 2.1 standard - for example 2.5.5 becomes "Target Size" again, and 4.1.1 Parsing is level A rather than removed:

wcagify('1.4.3', { version: '2.1' })
// link: 'https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html'

wcagify('2.4.11', { version: '2.1' })
// throws: criteria added in 2.2 are not part of WCAG 2.1

The byLevel and byImpact filters accept the same option.

Name lookups follow the version too: wcagify('target size', { version: '2.1' }) resolves to 2.5.5 because that was its name in 2.1, but the same lookup without the option throws - against WCAG 2.2 it would be a guess between "Target Size (Minimum)" and "Target Size (Enhanced)".

Listing criteria

The full criteria list and two filters are available for building checklists:

wcagify.criteria // all 87 criteria as the same objects wcagify() returns
wcagify.byLevel('AA') // only level AA criteria ('aa' works too)
wcagify.byImpact('Cognitive') // only criteria impacting cognitive accessibility

wcagify.criteria is frozen so nothing can corrupt the shared list - spread it ([...wcagify.criteria]) if you need to sort. The filters return fresh arrays you can do what you like with.

Command line

The same lookups work from a terminal:

npx wcagify 1.4.3
npx wcagify focus order
npx wcagify 1.4.3 --markdown   # [1.4.3 Contrast (Minimum)](https://...)
npx wcagify 1.4.3 --json
npx wcagify --level AA         # list every AA criterion
npx wcagify --level AA --impact Cognitive --markdown

Run npx wcagify --help for all options.

Nunjucks filter

You can use WCAGify in your Nunjucks templates using a filter. The filter needs a string value to work. For example:

{% set issue = '1.1.1'|wcagify %}

{{issue.criterion}} // 1.1.1 Non-text Content
{{issue.name}} // Non-text Content
{{issue.ref}} // 1.1.1
{{issue.url}} // https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html

Installing the Nunjucks filter

You need to expose the WCAGify function to Nunjucks as a simple filter. This wont make the macro work, this functionality just means we have the ability to call WCAGify from inside Nunjucks templates and return the object which you can use for your own Nunjucks templates. For example {{'1.1.1'|wcagify}}. If you need to return formatted HTML, use the supplied Macro or write your own.

An example server.js might look something like the following:

const nunjucks = require('nunjucks')
const express = require('express')

const app = express()

const env = nunjucks.configure('src', { express: app, })

// Add the Nunjucks filter
const wcagify = require('wcagify')
env.addFilter('wcagify', wcagify)

Nunjucks macro

There is an included macro if you don't want to template your own Nunjucks. It needs a string value to work. For example:

// Nunjucks code
{{ wcagify('1.1.1') }}

<!-- Output when compiled -->
<a href="https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html">
  1.1.1 Non-text Content
</a>

You can also pass in an object to set an ID and classes as optional parameters. For example:

// Nunjucks code
{{ wcagify('1.1.1', {
  id: 'wcag-ref-1',
  class: 'link link--small'
}) }}

<!-- Output when compiled -->
<a id="wcag-ref-1" class="link link--small" href="https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html">
  1.1.1 Non-text Content
</a>

Installing the Nunjucks macro

First, expose the location of the macro to your Nunjucks environment, and then make sure you've passed in the filter. The macro wont work without the filter as it calls it from inside the template. An example server.js file might look something like the following:

const path = require('path')
const nunjucks = require('nunjucks')
const express = require('express')

const app = express()

const paths = [
  ...
  // Add a link to the Nunjucks folder in the WCAGify module
  path.join(__dirname, 'node_modules', 'wcagify', 'nunjucks')
]

const env = nunjucks.configure(paths, { express: app, })

// Add the Nunjucks filter
const wcagify = require('wcagify')
env.addFilter('wcagify', wcagify)

Import the macro into your Nunjucks template and use it. For example:

// Imports from the .njk file from the node_modules path
{%- from 'wcagify.njk' import wcagify -%}

{{ wcagify('1.1.1', {
  id: 'wcag-ref-1',
  class: 'link link--small'
}) }}

Markdown macro

You can use WCAGify in your Markdown templates using MarkedJS as the renderer.

<!-- Markdown code -->
[1.1.1]({wcagify})

<!-- Output when compiled -->
<a href="https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html">
  1.1.1 Non-text Content
</a>

Installing the Markdown macro

The macro is a standard marked extension and needs marked v13 or later:

const { marked } = require('marked')
const wcagifyMarked = require('wcagify/markedjs')

marked.use(wcagifyMarked())

marked.parse('[1.1.1]({wcagify})')

Pass a version option to link to WCAG 2.1 instead:

marked.use(wcagifyMarked({ version: '2.1' }))

Tests

npm test