https://github.com/abbott567/wcagify
Gets information for WCAG 2.2 criteria based on a reference number.
https://github.com/abbott567/wcagify
a11y a11y-testing accessibility accessibility-reporter accessibility-testing wcag wcag2 wcag21 wcag22 wcag2a wcag2aa wcag2aaa
Last synced: 5 days ago
JSON representation
Gets information for WCAG 2.2 criteria based on a reference number.
- Host: GitHub
- URL: https://github.com/abbott567/wcagify
- Owner: abbott567
- Created: 2021-08-16T21:28:34.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-10-10T06:30:26.000Z (10 months ago)
- Last Synced: 2026-02-28T20:12:27.839Z (5 months ago)
- Topics: a11y, a11y-testing, accessibility, accessibility-reporter, accessibility-testing, wcag, wcag2, wcag21, wcag22, wcag2a, wcag2aa, wcag2aaa
- Language: JavaScript
- Homepage:
- Size: 68.4 KB
- Stars: 23
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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:
```javascript
const wcagify = require('wcagify')
```
In the following examples, all the function calls would return the same object.
```javascript
// 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:
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
{% 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:
```javascript
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:
```javascript
// Nunjucks code
{{ wcagify('1.1.1') }}
```
```html
You can also pass in an object to set an ID and classes as optional parameters. For example:
```javascript
// Nunjucks code
{{ wcagify('1.1.1', {
id: 'wcag-ref-1',
class: 'link link--small'
}) }}
```
```html
#### 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:
```javascript
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:
```javascript
// 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](https://www.npmjs.com/package/marked) as the renderer.
```markdown
[1.1.1]({wcagify})
```
```html
#### Installing the Markdown macro
The macro is a standard marked extension and needs marked v13 or later:
```javascript
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:
```javascript
marked.use(wcagifyMarked({ version: '2.1' }))
```
## Tests
```
npm test
```