diff --git a/doc/API.md b/doc/API.md index a41b59b2e6..fb40c90063 100644 --- a/doc/API.md +++ b/doc/API.md @@ -78,38 +78,27 @@ For a full listing of API offered by axe, clone the repository and run `npm run - The `"helpUrl"` in the results object is a link to a broader description of the accessibility issue and suggested remediation. These links point to Deque University help pages, which do not require a login. - Axe does not test hidden regions, such as inactive menus or modal windows. To test those for accessibility, write tests that activate or render the regions visible and run the analysis again. -### API Name: axe.getRules - -#### Purpose - -To get information on all the rules in the system. +### Axe-core Tags -#### Description +Each rule in axe-core has a number of tags. These provide metadata about the rule. Each rule has one tag that indicates which WCAG version / level it belongs to, or if it doesn't it have the `best-practice` tag. If the rule is required by WCAG, there is a tag that references the success criterion number. For example, the `wcag111` tag means a rule is required for WCAG 2 success criterion 1.1.1. -Returns a list of all rules with their ID and description +The `experimental`, `ACT` and `section508` tags are only added to some rules. Each rule with a `section508` tag also has a tag to indicate what requirement in old Section 508 the rule is required by. For example `section508.22.a`. -#### Synopsis +| Tag Name | Accessibility Standard / Purpose | +| ---------------- | ---------------------------------------------------- | +| `wcag2a` | WCAG 2.0 Level A | +| `wcag2aa` | WCAG 2.0 Level AA | +| `wcag21a` | WCAG 2.1 Level A | +| `wcag21aa` | WCAG 2.1 Level AA | +| `best-practice` | Common accessibility best practices | +| `wcag***` | WCAG success criterion e.g. wcag111 maps to SC 1.1.1 | +| `ACT` | W3C approved Accessibility Conformance Testing rules | +| `section508` | Old Section 508 rules | +| `section508.*.*` | Requirement in old Section 508 | +| `experimental` | Cutting-edge rules, disabled by default | +| `cat.*` | Category mappings used by Deque (see below) | -`axe.getRules([Tag Name 1, Tag Name 2...]);` - -#### Parameters - -- `tags` - **optional** Array of tags used to filter returned rules. If omitted, it will return all rules. - -**Returns:** Array of rules that match the input filter with each entry having a format of `{ruleId: , description: }` - -The current set of tags supported are listed in the following table: - -| Tag Name | Accessibility Standard / Purpose | -| --------------- | ------------------------------------------- | -| `wcag2a` | WCAG 2.0 Level A | -| `wcag2aa` | WCAG 2.0 Level AA | -| `wcag21a` | WCAG 2.1 Level A | -| `wcag21aa` | WCAG 2.1 Level AA | -| `best-practice` | Common accessibility best practices | -| `section508` | Old Section 508 rules | -| `experimental` | Cutting-edge rules, disabled by default | -| `cat.*` | Category mappings used by Deque (see below) | +All rules have a `cat.*` tag, which indicates what type of content it is part of. The following `cat.*` tags exist in axe-core: | Category name | | ----------------------------- | @@ -127,6 +116,26 @@ The current set of tags supported are listed in the following table: | `cat.text-alternatives` | | `cat.time-and-media` | +### API Name: axe.getRules + +#### Purpose + +To get information on all the rules in the system. + +#### Description + +Returns a list of all rules with their ID and description + +#### Synopsis + +`axe.getRules([Tag Name 1, Tag Name 2...]);` + +#### Parameters + +- `tags` - **optional** Array of tags used to filter returned rules. If omitted, it will return all rules. See [axe-core tags](#axe-core-tags). + +**Returns:** Array of rules that match the input filter with each entry having a format of `{ruleId: , description: }` + #### Example 1 In this example, we pass in the WCAG 2 A and AA tags into `axe.getRules` to retrieve only those rules. The function call returns an array of rules. @@ -201,7 +210,7 @@ axe.configure({ - `any` - array(optional, default `[]`). This is a list of checks that, if none "pass", will generate a violation. - `all` - array(optional, default `[]`). This is a list of checks that, if any "fails", will generate a violation. - `none` - array(optional, default `[]`). This is a list of checks that, if any "pass", will generate a violation. - - `tags` - array(optional, default `[]`). A list if the tags that "classify" the rule. In practice, you must supply some valid tags or the default evaluation will not invoke the rule. The convention is to include the standard (WCAG 2 and/or section 508), the WCAG 2 level, Section 508 paragraph, and the WCAG 2 success criteria. Tags are constructed by converting all letters to lower case, removing spaces and periods and concatenating the result. E.g. WCAG 2 A success criteria 1.1.1 would become ["wcag2a", "wcag111"] + - `tags` - array(optional, default `[]`). A list if the tags that "classify" the rule. See [axe-core tags](#axe-core-tags). - `matches` - function(optional, default `function() { return true }`). A filtering function that will exclude elements that match the `selector` property. - `disableOtherRules` - Disables all rules not included in the `rules` property. - `locale` - A locale object to apply (at runtime) to all rules and checks, in the same shape as `/locales/*.json`. @@ -399,16 +408,7 @@ Additionally, there are a number or properties that allow configuration of diffe ###### Options Parameter Examples -1. Run only Rules for an accessibility standard - -There are certain standards defined that can be used to select a set of rules. The defined standards and tag string are defined as follows: - -| Tag Name | Accessibility Standard | -| --------------- | :------------------------------: | -| `wcag2a` | WCAG 2.0 Level A | -| `wcag2aa` | WCAG 2.0 Level AA | -| `section508` | Section 508 | -| `best-practice` | Best practices endorsed by Deque | +1. Run only Rules for an accessibility standard. See [axe-core tags](#axe-core-tags). To run only WCAG 2.0 Level A rules, specify `options` as: diff --git a/doc/rule-descriptions.md b/doc/rule-descriptions.md index a327a0c5a8..fe97bff0b6 100644 --- a/doc/rule-descriptions.md +++ b/doc/rule-descriptions.md @@ -32,18 +32,18 @@ | [color-contrast](https://dequeuniversity.com/rules/axe/3.5/color-contrast?application=RuleDescription) | Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds | Serious | cat.color, wcag2aa, wcag143 | failure, needs review | | [definition-list](https://dequeuniversity.com/rules/axe/3.5/definition-list?application=RuleDescription) | Ensures <dl> elements are structured correctly | Serious | cat.structure, wcag2a, wcag131 | failure | | [dlitem](https://dequeuniversity.com/rules/axe/3.5/dlitem?application=RuleDescription) | Ensures <dt> and <dd> elements are contained by a <dl> | Serious | cat.structure, wcag2a, wcag131 | failure | -| [document-title](https://dequeuniversity.com/rules/axe/3.5/document-title?application=RuleDescription) | Ensures each HTML document contains a non-empty <title> element | Serious | cat.text-alternatives, wcag2a, wcag242 | failure | +| [document-title](https://dequeuniversity.com/rules/axe/3.5/document-title?application=RuleDescription) | Ensures each HTML document contains a non-empty <title> element | Serious | cat.text-alternatives, wcag2a, wcag242, ACT | failure | | [duplicate-id-active](https://dequeuniversity.com/rules/axe/3.5/duplicate-id-active?application=RuleDescription) | Ensures every id attribute value of active elements is unique | Serious | cat.parsing, wcag2a, wcag411 | failure | | [duplicate-id-aria](https://dequeuniversity.com/rules/axe/3.5/duplicate-id-aria?application=RuleDescription) | Ensures every id attribute value used in ARIA and in labels is unique | Critical | cat.parsing, wcag2a, wcag411 | failure | | [duplicate-id](https://dequeuniversity.com/rules/axe/3.5/duplicate-id?application=RuleDescription) | Ensures every id attribute value is unique | Minor | cat.parsing, wcag2a, wcag411 | failure | | [form-field-multiple-labels](https://dequeuniversity.com/rules/axe/3.5/form-field-multiple-labels?application=RuleDescription) | Ensures form field does not have multiple label elements | Moderate | cat.forms, wcag2a, wcag332 | needs review | | [frame-title](https://dequeuniversity.com/rules/axe/3.5/frame-title?application=RuleDescription) | Ensures <iframe> and <frame> elements contain a non-empty title attribute | Serious | cat.text-alternatives, wcag2a, wcag241, wcag412, section508, section508.22.i | failure, needs review | -| [html-has-lang](https://dequeuniversity.com/rules/axe/3.5/html-has-lang?application=RuleDescription) | Ensures every HTML document has a lang attribute | Serious | cat.language, wcag2a, wcag311 | failure | -| [html-lang-valid](https://dequeuniversity.com/rules/axe/3.5/html-lang-valid?application=RuleDescription) | Ensures the lang attribute of the <html> element has a valid value | Serious | cat.language, wcag2a, wcag311 | failure | -| [html-xml-lang-mismatch](https://dequeuniversity.com/rules/axe/3.5/html-xml-lang-mismatch?application=RuleDescription) | Ensure that HTML elements with both valid lang and xml:lang attributes agree on the base language of the page | Moderate | cat.language, wcag2a, wcag311 | failure | +| [html-has-lang](https://dequeuniversity.com/rules/axe/3.5/html-has-lang?application=RuleDescription) | Ensures every HTML document has a lang attribute | Serious | cat.language, wcag2a, wcag311, ACT | failure | +| [html-lang-valid](https://dequeuniversity.com/rules/axe/3.5/html-lang-valid?application=RuleDescription) | Ensures the lang attribute of the <html> element has a valid value | Serious | cat.language, wcag2a, wcag311, ACT | failure | +| [html-xml-lang-mismatch](https://dequeuniversity.com/rules/axe/3.5/html-xml-lang-mismatch?application=RuleDescription) | Ensure that HTML elements with both valid lang and xml:lang attributes agree on the base language of the page | Moderate | cat.language, wcag2a, wcag311, ACT | failure | | [image-alt](https://dequeuniversity.com/rules/axe/3.5/image-alt?application=RuleDescription) | Ensures <img> elements have alternate text or a role of none or presentation | Critical | cat.text-alternatives, wcag2a, wcag111, section508, section508.22.a | failure, needs review | | [input-button-name](https://dequeuniversity.com/rules/axe/3.5/input-button-name?application=RuleDescription) | Ensures input buttons have discernible text | Critical | cat.name-role-value, wcag2a, wcag412, section508, section508.22.a | failure, needs review | -| [input-image-alt](https://dequeuniversity.com/rules/axe/3.5/input-image-alt?application=RuleDescription) | Ensures <input type="image"> elements have alternate text | Critical | cat.text-alternatives, wcag2a, wcag111, section508, section508.22.a | failure, needs review | +| [input-image-alt](https://dequeuniversity.com/rules/axe/3.5/input-image-alt?application=RuleDescription) | Ensures <input type="image"> elements have alternate text | Critical | cat.text-alternatives, wcag2a, wcag111, section508, section508.22.a, ACT | failure, needs review | | [label](https://dequeuniversity.com/rules/axe/3.5/label?application=RuleDescription) | Ensures every form element has a label | Minor, Critical | cat.forms, wcag2a, wcag412, wcag131, section508, section508.22.n | failure, needs review | | [link-name](https://dequeuniversity.com/rules/axe/3.5/link-name?application=RuleDescription) | Ensures links have discernible text | Serious | cat.name-role-value, wcag2a, wcag412, wcag244, section508, section508.22.a | failure, needs review | | [list](https://dequeuniversity.com/rules/axe/3.5/list?application=RuleDescription) | Ensures that lists are structured correctly | Serious | cat.structure, wcag2a, wcag131 | failure | diff --git a/lib/rules/document-title.json b/lib/rules/document-title.json index 4ec54f5fff..2aba304b6b 100644 --- a/lib/rules/document-title.json +++ b/lib/rules/document-title.json @@ -2,7 +2,7 @@ "id": "document-title", "selector": "html", "matches": "window-is-top-matches", - "tags": ["cat.text-alternatives", "wcag2a", "wcag242"], + "tags": ["cat.text-alternatives", "wcag2a", "wcag242", "ACT"], "metadata": { "description": "Ensures each HTML document contains a non-empty element", "help": "Documents must have <title> element to aid in navigation" diff --git a/lib/rules/html-has-lang.json b/lib/rules/html-has-lang.json index 6c0d93243c..0fd137af85 100644 --- a/lib/rules/html-has-lang.json +++ b/lib/rules/html-has-lang.json @@ -2,7 +2,7 @@ "id": "html-has-lang", "selector": "html", "matches": "window-is-top-matches", - "tags": ["cat.language", "wcag2a", "wcag311"], + "tags": ["cat.language", "wcag2a", "wcag311", "ACT"], "metadata": { "description": "Ensures every HTML document has a lang attribute", "help": "<html> element must have a lang attribute" diff --git a/lib/rules/html-lang-valid.json b/lib/rules/html-lang-valid.json index 23a1f8c492..7848bd3a1b 100644 --- a/lib/rules/html-lang-valid.json +++ b/lib/rules/html-lang-valid.json @@ -1,7 +1,7 @@ { "id": "html-lang-valid", "selector": "html[lang], html[xml\\:lang]", - "tags": ["cat.language", "wcag2a", "wcag311"], + "tags": ["cat.language", "wcag2a", "wcag311", "ACT"], "metadata": { "description": "Ensures the lang attribute of the <html> element has a valid value", "help": "<html> element must have a valid value for the lang attribute" diff --git a/lib/rules/html-xml-lang-mismatch.json b/lib/rules/html-xml-lang-mismatch.json index 157191f5fc..0d8bcc6591 100644 --- a/lib/rules/html-xml-lang-mismatch.json +++ b/lib/rules/html-xml-lang-mismatch.json @@ -2,7 +2,7 @@ "id": "html-xml-lang-mismatch", "selector": "html[lang][xml\\:lang]", "matches": "xml-lang-mismatch-matches", - "tags": ["cat.language", "wcag2a", "wcag311"], + "tags": ["cat.language", "wcag2a", "wcag311", "ACT"], "metadata": { "description": "Ensure that HTML elements with both valid lang and xml:lang attributes agree on the base language of the page", "help": "HTML elements with lang and xml:lang must have the same base language" diff --git a/lib/rules/input-image-alt.json b/lib/rules/input-image-alt.json index 8b76079935..fff61ea206 100644 --- a/lib/rules/input-image-alt.json +++ b/lib/rules/input-image-alt.json @@ -6,7 +6,8 @@ "wcag2a", "wcag111", "section508", - "section508.22.a" + "section508.22.a", + "ACT" ], "metadata": { "description": "Ensures <input type=\"image\"> elements have alternate text",