Custom Rulesets

A custom ruleset is a generated JSON file that is passed to axe.configure in order to control how axe tests your page. It can modify how existing rules run, such as disabling them or changing their impact, or can be used to create entirely new rules.

Some of the things you can do with custom rulesets include:

• Change rule or check impact.
• Disable rules.
• Create new rules to test your organisations accessibility policy.
• Restrict what solutions are allowed for elements. For example not allowing the title attribute to give an <img> element an accessible name.
• Modify the minimal contrast in the color-contrast rule.
• Update which ARIA roles and properties are supported.

The "ruleset" command has the following format:

axe ruleset [options]

Options

-c, --custom <path>

Generate custom ruleset from a changes.json file in the current directory or from the specified path.

-d, --destination <path>

Output directory for the ruleset JSON file

-t, --tags <list>

List of comma separated tags that will be used to filter the standard rule set

-f, --format [format]

Output format (js, or json) for the ruleset JSON file

-l, --log

Generate a list of all the rules included in the generated ruleset(s).

-x, --disable-other-rules

Disables all rules not included in the rules property of the changes.json file or the rules directory.

-a, --axe-source <path>

Path to a custom axe source file

--508 [filename]

Generate standard config for Section 508 rules.

--en301549 [filename]

Generate standard config for EN 301 549 rules.

--ttv5 [filename]

Generate standard config for Trusted Tester v5 rules.

--wcag2 [filename]

Generate standard config for WCAG 2.0 guidelines.

--wcag21 [filename]

Generate standard config for WCAG 2.1 guidelines.

--wcag22 [filename]

Generate standard config for WCAG 2.2 guidelines.

--wcag2aaa [filename]

Generate standard config for WCAG 2.0 Level AAA guidelines.

--wcag21aaa [filename]

Generate standard config for WCAG 2.1 Level AAA guidelines.

--wcag22aaa [filename]

Generate standard config for WCAG 2.2 Level AAA guidelines.

--all [filename]

Generate standard config for all guidelines (508, WCAG 2, and WCAG 2.1).

--only-changes

Generate only the changes and additions to the ruleset and not the complete config.

Generating a custom ruleset

To generate a custom ruleset you will need to have a changes.json file, either in the current directory or in the path specified by the --custom option.

The changes.json file has the same format as the object passed to axe.configure. In the file you can specify the changes to current axe rules and checks, as well as any new rules or checks.

For example, if you wanted to change the impact of the valid-lang rule to be minor instead of serious, the changes.json file would look something like the following:

{
    "rules": [{
        "id": "valid-lang",
        "impact": "minor"
    }]
}

Using Rules and Checks Directories

If you wish, you can also separate new rules and checks into their own directories (named rules and checks respectively). Each rule or check should be its own JSON file in their respective directory. Doing this doesn't change the output of the generated JSON file, but is merely a convenient way to organize multiple custom rules and checks instead of listing them all in the changes.json file.

For example, to create a new custom rule called h1-no-duplicate which checks if there is more than one <h1> element on the page, you might have the following directory structure:

directory
 ├ changes.json
 ├ rules
 │  └ h1-no-duplicate.json
 └ checks
    └ page-no-duplicate-h1.json

The h1-no-duplicate.json rule metadata file would define the custom rule and which checks to use:

{
    "id": "h1-no-duplicate",
    "selector": "h1:not([role]), [role=heading][aria-level=1]",
    "tags": ["cat.semantics", "best-practice"],
    "metadata": {
        "description": "Ensures the document has at most one h1 element",
        "help": "Document must not have more than one h1 element"
    },
    "all": [],
    "any": ["page-no-duplicate-h1"],
    "none": []
}

The page-no-duplicate-h1.json check metadata file would define the custom check and which axe evaluate method to use:

{
    "id": "page-no-duplicate-h1",
    "evaluate": "page-no-duplicate-evaluate",
    "after": "page-no-duplicate-after",
    "options": {
        "selector": "h1:not([role]), [role=heading][aria-level=1]"
    },
    "metadata": {
        "impact": "moderate",
        "messages": {
            "pass": "Document does not have more than one h1 element",
            "fail": "Document has more than one h1 element"
        }
    }
}

Lastly, since there are no changes to current rules or checks, the changes.json file would be an empty object:

{}

After running the axe ruleset --custom command, the generated JSON file would look as follows:

{
    "rules": [{
        "id": "h1-no-duplicate",
        "selector": "h1:not([role]), [role=heading][aria-level=1]",
        "tags": ["cat.semantics", "best-practice"],
        "metadata": {
            "description": "Ensures the document has at most one h1 element",
            "help": "Document must not have more than one h1 element"
        },
        "all": [],
        "any": ["page-no-duplicate-h1"],
        "none": []
    }],
    "checks": [{
        "id": "page-no-duplicate-h1",
        "evaluate": "page-no-duplicate-evaluate",
        "after": "page-no-duplicate-after",
        "options": {
            "selector": "h1:not([role]), [role=heading][aria-level=1]"
        },
        "metadata": {
            "impact": "moderate",
            "messages": {
                "pass": "Document does not have more than one h1 element",
                "fail": "Document has more than one h1 element"
            }
        }
    }]
}

Using a custom ruleset

There are three ways to configure custom rules in axe DevTools.

• explicitly: This differs between packages, for CLI, use the --custom flag.

• environment variable: If there is an AXE_RULESET_PATH environment variable set, axe DevTools will load it as the default ruleset.

• local file: If there is an axe-ruleset.json file in the directory where axe runs, it will be used as the default ruleset.

If none of these are specified, or if axe DevTools is unable to load whatever file was set, the wcag2 default ruleset will be used instead.

Support

Creating custom rulesets requires a significant understanding of axe-core. For details, see the axe-core API documentation. If you would like support on creating and maintaining your custom ruleset, contact your Deque representative.