govuk_publishing_components 16.6.0 → 16.7.0

data/node_modules/axe-core/doc/accessibility-supported.md

@@ -0,0 +1,33 @@
+# How we make decisions on rules
+
+In order to adhere to the manifesto and at the same time be useful to developers and content creators, we evaluate all rules according to strict normative WCAG 2 interpretation. We also pay very strong attention to the normative portion of WCAG 2 known as [accessibility supported](https://www.w3.org/TR/WCAG20/#accessibility-supporteddef).
+
+## Accessibility supported
+
+Boiled-down, accessibility supported means that in order for a technique to be valid, it must work on all viable platforms for all assitive technology that are widely used and freely available (paraphrased).
+
+We currently test the following AT combinations for support
+
+1. VoiceOver and Safari on OS X
+1. VoiceOver and Safari on iOS
+1. JAWS and IE on Windows
+1. NVDA and Firefox on Windows
+1. Talkback and Chrome on Android
+1. Dragon and Firefox on Windows
+
+## Impact on ARIA
+
+For some technologies, like ARIA, we have a dilemma in that the spec is approved before supported and we have to weigh a balance between something that conforms to the spec, but does not yet work. When we do this, we favor the accessibility supported principle over the spec but we temper this with the impact of using an unsupported feature. Here is how we do this:
+
+1. If the feature's use is supported by all platforms: allow, else
+1. If the feature's use does not have a negative impact on accessibility: allow, else
+1. If we can detect a fallback: allow, else
+1. disallow the feature's use until it is supported
+
+In addition, we disallow invalid attributes starting with `aria-` and invalid attribute values as these are highly likely to have a negative impact on accessibility because of the scenarios under which these are likely to occur (this is so we can act as a useful linting tool for developers).
+
+## Best practices
+
+We recognize that there are best practices that significantly improve the usability of application, even though they are not strictly required in order to conform with WCAG 2. We develop the best practice rules to help content developers to identify these and adhere to them.
+
+We recognize that this topic is somewhat controvertial and the rules we have represent Deque's opinion on what constitutes a best practice.

data/node_modules/axe-core/doc/act-rules-format.md

@@ -0,0 +1,37 @@
+# W3C Standardized Rules
+
+Deque Systems is one of leading organizations in the development of standardized accessibility conformance testing rules. The [axe-core rules proposal format](./rule-proposal.md) is an adaptation of the [Accessibility Conformance Testing Rules Format](https://www.w3.org/TR/act-rules-format/).
+
+There are two ways a rule written in the axe-core rule format can be transformed into the ACT Rules format:
+
+## Method 1: Create a single rule
+
+This method is useful for rules with a small number of checks.
+
+1. Add the test input type to it: `rendered page`
+2. Add an `assumptions` section, add possible assumptions to it
+3. Add an `outcomes` section, describing the different possible outcomes of the rule
+4. Add a `Validation Tests` section, that links to the integration tests
+5. Update the check to return pass/fail/cantTell instead of true/false/undefined
+6. Add control flow to the checks:
+
+- `any` checks should only return `fail` in the last step. All steps leading up to it either return `pass` or say `continue to the next step`.
+- `all` and `none` checks should only return `pass` in the last step. All steps leading up to it either return `fail` or say `continue to the next step`.
+
+7. Rename `checks` to `steps` and add a `step X` (where X is the step number) to the heading with the check name.
+8. Replace the `tags` section with a `Accessibility Requirements`. The requirements can be determined based on the `wcag###` tags.
+
+## Method 2: Create a rule group
+
+This method is useful for larger rules with `any` checks. This effectively turns every check into its own rule, and turns the rule into a rule group.
+
+1. Copy each check into a new document
+2. Add a `steps` heading
+3. Add the test input type to it: `rendered page`
+4. Add an `assumptions` section, add possible assumptions to it
+5. Add an `outcomes` section, describing the different possible outcomes of the rule
+6. Copy the `selector` section from the original rule into the new rule documents
+7. Update the check to return pass/fail/cantTell instead of true/false/undefined
+8. Add a `Validation Tests` section, that links to only those integration tests relevant for this check (now a new rule).
+9. Indicate that the new rule is part of a group, using the original axe-core rule ID as the group name.
+10. Replace the `tags` section with a `Accessibility Requirements`. The requirements can be determined based on the `wcag###` tags.

data/node_modules/axe-core/doc/aria-supported.md

@@ -0,0 +1,23 @@
+# ARIA Roles and Attributes unsupported in axe-core.
+
+It can be difficult to know which features of web technologies are accessible across different platforms, and with different screen readers and other assistive technologies. Axe-core does some of this work for you, by raising issues when accessibility features are used that are known to cause problems.
+
+This page contains a list of ARIA 1.1 features that axe-core raises as unsupported. For more information, read [We’ve got your back with “Accessibility Supported” in axe](https://www.deque.com/blog/weve-got-your-back-with-accessibility-supported-in-axe/).
+
+For a detailed description about how accessibility support is decided, see [How we make decisions on rules](accessibility-supported.md).
+
+## Roles
+
+| aria-role | axe-core support |
+| --------- | ---------------- |
+| figure    | No               |
+
+## Attributes
+
+| aria-attribute       | axe-core support |
+| -------------------- | ---------------- |
+| aria-describedat     | No               |
+| aria-details         | No               |
+| aria-roledescription | Mixed[^1]        |
+
+[^1]: Supported on elements: `<button>`, `<input type="button" | "checkbox" | "image" | "radio" | "reset" | "submit">`, `<img>`, `<select>`, `<summary>`

data/node_modules/axe-core/doc/code-submission-guidelines.md

@@ -0,0 +1,178 @@
+# Code Submission Guidelines
+
+We've enacted standards for commits and pull requests to effectively manage the project over
+time. We expect all code contributed to follow these standards. If your code doesn't follow them, we
+will kindly ask you to resubmit it in the correct format.
+
+- [Git Commits](#git-commits)
+- [Submitting a pull request](#submitting-a-pull-request)
+- [Merging a pull request](#merging-a-pull-request)
+- [Squashing Commits](#squashing-everything-into-one-commit)
+
+## Git Commits
+
+We follow Angular's code contribution style with precise rules for formatting git commit messages.
+This leads to more readable messages that are easy to follow when looking through the project
+history. We will also use commit messages to generate the aXe Changelog document.
+
+A detailed explanation of Angular's guidelines and conventions can be found [on Google Docs](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#).
+
+### Commit Message Format
+
+Each commit message should consist of a header, a body and a footer. The header has a special format
+that includes a type, a scope and a subject. Here's a sample of the format:
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+### Here's an example:
+
+```sh
+perf(rule): improve speed of color contrast rules
+
+  Use async process to compare elements without UI lockup
+
+    Closes #1
+```
+
+> Commit messages should be 100 characters or less to make them easy to read on Github and
+> various git tools.
+
+### How to structure your commits:
+
+#### Type
+
+Must be one of the following:
+
+- **feat:** A new feature
+- **fix:** A bug fix
+- **docs:** Documentation only changes
+- **style:** Changes that do not affect the meaning of the code (white-space, formatting, missing
+  semi-colons, etc)
+- **refactor:** A code change that neither fixes a bug nor adds a feature
+- **perf:** A code change that improves performance
+- **test:** Adding missing tests
+- **chore:** Changes to the build process or auxiliary tools and libraries such as documentation
+  generation
+
+#### Scope
+
+The scope specifies the place of the commit change in the codebase along with the type. It could
+reference a rule, a commons file, or anything really. E.g. `feat(rule)` or
+`test(commons/aria)`. It would help us call to out rule changes in our changelog with `rule` used as the scope.
+
+If the scope is too broad to summarize, use the type only and leave off the parentheses. E.g.
+`type: some subject`. Keep in mind that a long scope often pushes your commit message over 100 characters.
+Brevity is helpful for everyone!
+
+#### Subject
+
+The subject contains succinct description of the change:
+
+- use the imperative, present tense: "change" not "changed" nor "changes"
+- don't capitalize first letter
+- no dot (.) at the end
+
+#### Body
+
+Use the imperative, present tense: "change" not "changed" nor "changes", just like the subject.
+Include the motivation for the change and contrast it with how the code worked before.
+
+#### Footer
+
+Reference any issue that this commit closes with its fully qualified URL to support both
+Bitbucket and Github.
+
+If needed, the footer should contain any information about Breaking Changes. Deprecation notices or
+breaking changes in the Changelog should inform users if they'll need to modify their code after
+this commit.
+
+## Submitting a pull request
+
+We want to keep our commit log clean by avoiding merge messages in branches. Before submitting a pull request, make sure your branch is up to date with the develop branch by either:
+
+- Pulling from develop before creating your branch
+- Doing a rebase from origin/develop (will require a force push **on your branch**)
+
+To rebase from origin/develop if we've pushed changes since you created your branch:
+
+```sh
+git checkout your-branch
+git fetch
+git rebase origin/develop
+git push origin head -f
+```
+
+## Merging a pull request
+
+If a pull request has many commits (especially if they don't follow our [commit policy](#git-commits)), you'll want to squash them into one clean commit.
+
+In the Github UI, you can use the new [Squash and Merge](https://github.com/blog/2141-squash-your-commits) feature to make this easy. If there are merge conflicts preventing this, either ask the committer to rebase from develop following the [PR submission steps above](#submitting-a-pull-request), or use the manual method below.
+
+To apply a pull request manually, make sure your local develop branch is up to date. Then, create a new branch for that pull request.
+
+Create a temporary, local branch:
+
+```sh
+git checkout -b temp-feature-branch
+```
+
+Run the following commands to apply all commits from that pull request on top of your branch's local history:
+
+```console
+curl -L https://github.com/dequelabs/axe-core/pull/205.patch | git am -3
+```
+
+If the merge succeeds, use `git diff origin/develop` to review all the changes that will happen
+post-merge.
+
+## Squashing everything into one commit
+
+Before merging a pull request with many commits into develop, make sure there is only one commit representing the
+changes in the pull request, so the git log stays lean. We particularly want to avoid merge messages and vague commits that don't follow our commit policy (like `Merged develop into featurebranch` or `fixed some stuff`).
+
+You can use git's interactive rebase to manipulate, merge, and rename commits in your local
+history. If these steps are followed, a force push shouldn't be necessary.
+
+**Do not force push to develop or master under any circulstances.**
+
+To interactively rebase all of your commits on top of the latest in develop, run:
+
+```sh
+git rebase --interactive origin/develop
+```
+
+This brings up an interactive dialog in your text editor. Follow the instructions to squash all
+of your commits into the top one. Rename the top one.
+
+Once this is done, run `git log` and you will see only one commit after develop, representing
+everything from the pull request.
+
+Finally, pull from develop with `rebase` to put all of our local commits on top of the latest
+remote.
+
+```sh
+git pull --rebase origin develop
+```
+
+You can then push the latest code to develop (note that force push isn't needed if these steps are followed):
+
+```console
+git push origin develop
+```
+
+## Writing Integration Tests
+
+For each rule, axe-core needs to have integration tests. These tests are located in `tests/integration`.
+This directory contains two other directories. `rules`, which contains integration tests that can be run
+on a single page, and `full` which contains tests that can only be tested by running on multiple pages.
+
+Ensure that for each check used in the rule, there is an integration test for both pass and fail results.
+Integration tests put in `rules` can be described using simple code snippets in an HTML file, and a JSON
+file that describes the expected outcome. For `full` tests, a complete Jasmine test should be created,
+including at least one HTML file that has the tested code, and a JS file that has the test statements.

data/node_modules/axe-core/doc/developer-guide.md

@@ -0,0 +1,500 @@
+# aXe Developer Guide
+
+aXe runs a series of tests to check for accessibility of content and functionality on a website. A test is made up of a series of Rules which are, themselves, made up of Checks. aXe executes these Rules asynchronously and, when the Rules are finished running, runs a callback function which is passed a Result structure. Since some Rules run on the page level while others do not, tests will also run in one of two ways. If a document is specified, the page level rules will run, otherwise they will not.
+
+aXe 3.0 supports open Shadow DOM: see our virtual DOM APIs and test utilities for developing axe-core moving forward. Note: we do not and cannot support closed Shadow DOM.
+
+1. [Getting Started](#getting-started)
+1. [Architecture Overview](#architecture-overview)
+   1. [Rules](#rules)
+   1. [Checks](#checks)
+   1. [Common Functions](#common-functions)
+   1. [Virtual Nodes](#virtual-nodes)
+   1. [Core Utilities](#core-utilities)
+1. [Virtual DOM APIs](#virtual-dom-apis)
+   1. [API Name: axe.utils.getFlattenedTree](#api-name-axeutilsgetflattenedtree)
+   1. [API Name: axe.utils.getNodeFromTree](#api-name-axeutilsgetnodefromtree)
+1. [Test Utilities](#test-utilities)
+   1. [Test Util Name: axe.testUtils.MockCheckContext](#test-util-name-axetestutilsmockcheckcontext)
+   1. [Test Util Name: axe.testUtils.shadowSupport](#test-util-name-axetestutilsshadowsupport)
+   1. [Test Util Name: axe.testUtils.fixtureSetup](#test-util-name-axetestutilsfixturesetup)
+   1. [Test Util Name: axe.testUtils.checkSetup](#test-util-name-axetestutilschecksetup)
+1. [Using Rule Generation CLI](#axe-rule-generator)
+
+## Getting Started
+
+### Environment Pre-requisites
+
+1. You must have NodeJS installed.
+2. Grunt must be installed globally. `npm install -g grunt-cli` (You may need to do this as `sudo npm install -g grunt-cli`)
+3. Install npm development dependencies. In the root folder of your axe-core repository, run `npm install`
+
+### Building axe.js
+
+To build axe.js, simply run `grunt build` in the root folder of the axe-core repository. axe.js and axe.min.js are placed into the `dist` folder.
+
+### Running Tests
+
+To run all tests from the command line you can run `grunt test`, which will run all unit and integration tests using PhantomJS and Selenium Webdriver.
+
+You can also load tests in any supported browser, which is helpful for debugging. Tests require a local server to run, you must first start a local server to serve files. You can use Grunt to start one by running `grunt dev`. Once your local server is running you can load the following pages in any browser to run tests:
+
+1. [Core Tests](../test/core/)
+2. [Commons Tests](../test/commons/)
+3. [Check Tests](../test/checks/)
+4. [Integration Tests](../test/integration/rules/)
+5. There are additional tests located in [test/integration/full/](../test/integration/full/) for tests that need to be run against their own document.
+
+### API Reference
+
+[See API exposed on aXe](./API.md#section-2-api-reference)
+
+## Architecture Overview
+
+aXe tests for accessibility using objects called Rules. Each Rule tests for a high-level aspect of accessibility, such as color contrast, button labels, and alternate text for images. Each rule is made up of a series of Checks. Depending on the rule; all, some, or none of these checks must pass in order for the rule to pass.
+
+Upon execution, a Rule runs each of its Checks against all relevant nodes. Which nodes are relevant is determined by the Rule's `selector` property and `matches` function. If a Rule has no Checks that apply to a given node, the Rule will result in an inapplicable result.
+
+After execution, a Check will return `true` or `false` depending on whether or not the tested condition was satisfied. The result, as well as more information on what caused the Check to pass or fail, will be stored in either the `passes` array or the `violations` array.
+
+### Rules
+
+Rules are defined by JSON files in the [lib/rules directory](../lib/rules). The JSON object is used to seed the [Rule object](../lib/core/base/rule.js#L30). A valid Rule JSON consists of the following:
+
+- `id` - `String` A unique name of the Rule.
+- `selector` - **optional** `String` which is a CSS selector that specifies the elements of the page on which the Rule runs. aXe-core will look inside of the light DOM and _open_ [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM) trees for elements matching the provided selector. If omitted, the rule will run against every node.
+- `excludeHidden` - **optional** `Boolean` Whether the rule should exclude hidden elements. Defaults to `true`.
+- `enabled` - **optional** `Boolean` Whether the rule is enabled by default. Defaults to `true`.
+- `pageLevel` - **optional** `Boolean` Whether the rule is page level. Page level rules will only run if given an entire `document` as context.
+- `matches` - **optional** `String` Relative path to the JavaScript file of a custom matching function. See [matches function](#matches-function) for more information.
+- `tags` - **optional** `Array` Strings of the accessibility guidelines of which the Rule applies.
+- `metadata` - `Object` Consisting of:
+  - `description` - `String` Text string that describes what the rule does.
+  - `helpUrl` - `String` **optional** URL that provides more information about the specifics of the violation. Links to a page on the Deque University site.
+  - `help` - `String` Help text that describes the test that was performed.
+- `any` - `Array` Checks that make up this Rule; one of these checks must return `true` for a Rule to pass.
+- `all` - `Array` Checks that make up this Rule; all these checks must return `true` for a Rule to pass.
+- `none` - `Array` Checks that make up this Rule; none of these checks must return `true` for a Rule to pass.
+
+The `any`, `all` and `none` arrays must contain either a `String` which references the `id` of the Check; or an object of the following format:
+
+- `id` - `String` The unique ID of the Check.
+- `options` - `Mixed` Any options the Check requires that are specific to the Rule.
+
+There is a Grunt target which will ensure each Rule has a valid format, which can be run with `grunt validate`.
+
+#### Matches Function
+
+Custom `matches` functions are executed against each node which matches the Rule's `selector` and receive two parameters:
+
+- `node` – node, the DOM Node to test
+- `virtualNode`– object, the virtual DOM representation of the node. See [virtualNode documentation](#virtual-nodes) for more.
+
+The matches function must return either `true` or `false`. Common functions are provided as `commons`. [See the data-table matches function for an example.](../lib/rules/data-table-matches.js)
+
+### Checks
+
+Similar to Rules, Checks are defined by JSON files in the [lib/checks directory](../lib/checks). The JSON object is used to seed the [Check object](../lib/core/base/check.js). A valid Check JSON consists of the following:
+
+- `id` - `String` A unique name of the Check
+- `evaluate` - `String` Relative path to the JavaScript file which contains the function body of the Check itself
+- `after` - **optional** `String` Relative path to the JavaScript file which contains the function body of a Check's after (or post-processing) function.f
+- `options` - **optional** `Mixed` Any information the Check needs that you might need to customize and/or is locale specific. Options can be overridden at runtime (with the options parameter) or config-time. For example, the [valid-lang](../lib/checks/language/valid-lang.json) Check defines what ISO 639-1 language codes it should accept as valid. Options do not need to follow any specific format or type; it is up to the author of a Check to determine the most appropriate format.
+- `metadata` - `Object` Consisting of:
+  - `impact` - `String` (one of `minor`, `moderate`, `serious`, or `critical`)
+  - `messages` - `Object` These messages are displayed when the Check passes or fails
+    - `pass` - `String` [doT.js](http://olado.github.io/doT/) template string displayed when the Check passes
+    - `fail` - `String` [doT.js](http://olado.github.io/doT/) template string displayed when the Check fails
+    - `incomplete` – `String|Object` – [doT.js](http://olado.github.io/doT/) template string displayed when the Check is incomplete OR an object with `missingData` on why it returned incomplete. Refer to [rules.md](./rules.md).
+
+#### Check `evaluate`
+
+A Check's evaluate function is run a special context in order to give access to APIs which provide more information. Checks will run against a single node and do not have access to other frames. A Check must either return `true` or `false`.
+
+The following variables are defined for `Check#evaluate`:
+
+- `node` - `HTMLElement` The element that the Check is run against
+- `options` - `Mixed` Any options specific to this Check that may be necessary. If not specified by the user at run-time or configure-time; it will use `options` as defined by the Check's JSON file.
+- `virtualNode` – `Object` The virtualNode object for use with Shadow DOM. See [virtualNode documentation](#virtual-nodes).
+- `this.data()` - `Function` Free-form data that either the Check message requires or is presented as `data` in the CheckResult object. Subsequent calls to `this.data()` will overwrite previous. See [aria-valid-attr](../lib/checks/aria/valid-attr.js) for example usage.
+- `this.relatedNodes()` - `Function` Array or NodeList of elements that are related to this Check. For example the [duplicate-id](../lib/checks/shared/duplicate-id.js) Check will add all Elements which share the same ID.
+- `commons` - Common functions that may be used across multiple Checks. See [Common Functions](#common-functions) for more information.
+
+#### Check `after`
+
+You can use the `after` function to evaluate nodes that might be in other frames or to filter the number of violations or passes produced. The `after` function runs once for each Rule in the top-most (or originating) frame. Due to this, you should not perform DOM operations in after functions, but instead operate on `data` defined by the Check.
+
+For example, the [duplicate-id](../lib/checks/shared/duplicate-id.json) Check include an [after function](../lib/checks/shared/duplicate-id-after.js) which reduces the number of violations so that only one violation per instance of a duplicate ID is found.
+
+The following variables are defined for `Check#after`:
+
+- `results` - `Array` Contains [CheckResults](#checkresult) for every matching node.
+- `commons` - Common functions that may be used across multiple Checks. See [Common Functions](#common-functions) for more information.
+
+The after function must return an `Array` of CheckResults, due to this, it is a very common pattern to just use `Array#filter` to filter results:
+
+```js
+var uniqueIds = [];
+return results.filter(function(r) {
+	if (uniqueIds.indexOf(r.data) === -1) {
+		uniqueIds.push(r.data);
+		return true;
+	}
+	return false;
+});
+```
+
+#### Pass, Fail and Incomplete Templates
+
+Occasionally, you may want to add additional information about why a Check passed, failed or returned undefined into its message. For example, the [aria-valid-attr](../lib/checks/aria/valid-attr.json) will add information about any invalid ARIA attributes to its fail message. The message uses the [doT.js](http://olado.github.io/doT/) and is compiled to a JavaScript function at build-time. In the Check message, you have access to the `CheckResult` as `it`.
+
+```js
+// aria-valid-attr check
+"messages": {
+  "pass": "ARIA attributes are used correctly for the defined role",
+  "fail": "ARIA attribute{{=it.data && it.data.length > 1 ? 's are' : ' is'}} not allowed:{{~it.data:value}} {{=value}}{{~}}",
+  "incomplete": "axe-core couldn't tell because of {{it.data.missingData}}"
+}
+```
+
+See [Developing Axe-core Rules](./rule-development.md) for more information
+on writing rules and checks, including incomplete results.
+
+#### CheckResult
+
+When a Check is executed, its result is then added to a [CheckResult object](../lib/core/base/check-result.js). Much like the RuleResult object, the CheckResult object only contains information that is required to determine whether a Check, and its parent Rule passed or failed. `metadata` from the originating Check is combined later and will not be available until aXe reaches the reporting stage.
+
+A CheckResult has the following properties:
+
+- `id` - `String` The ID of the Check this CheckResult belongs to.
+- `data` - `Mixed` Any data the Check's evaluate function added with `this.data()`. Typically used to insert data from analysis into a message or to perform further tests in the post-processing function.
+- `relatedNodes` - `Array` Nodes that are related to the current Check as defined by [check.evaluate](#check-evaluate).
+- `result` - `Boolean` The return value of [check.evaluate](#check-evaluate).
+
+### Common Functions
+
+Common functions are an internal library used by the rules and checks. If you have code repeated across rules and checks, you can use these functions and contribute to them. They are made available to every function as `commons`. Documentation is available in [source code](../lib/commons/).
+
+#### Commons and Shadow DOM
+
+To support open Shadow DOM while maintaining backwards compatibility, commons functions that
+query DOM nodes must operate on an in-memory representation of the DOM using aXe-core’s
+built-in [API methods and utility functions](./API.md#virtual-dom-utilities).
+
+Commons functions should do the virtual tree lookup and call a `virtual` function
+including the rest of the commons code. The naming of this special function
+should contain the original commons function name with `Virtual` added to signify
+it expects to operate on a virtual DOM tree.
+
+Let’s look at an example:
+
+```js
+axe.commons.text.accessibleText = function(element, inLabelledbyContext) {
+	let virtualNode = axe.utils.getNodeFromTree(axe._tree[0], element); // throws an exception on purpose if axe._tree not correct
+	return axe.commons.text.accessibleTextVirtual(
+		virtualNode,
+		inLabelledbyContext
+	);
+};
+
+axe.commons.text.accessibleTextVirtual = function(
+	element,
+	inLabelledbyContext
+) {
+	// rest of the commons code minus the virtual tree lookup, since it’s passed in
+};
+```
+
+`accessibleTextVirtual` would only be called directly if you’ve got a virtual node
+you can use. If you don’t already have one, call the `accessibleText` lookup function,
+which passes on a virtual DOM node with both the light DOM and Shadow DOM (if applicable).
+
+### Virtual Nodes
+
+To support open Shadow DOM, aXe-core has the ability to handle virtual nodes in [rule matches](#matches-function)
+and [check evaluate](#check-evaluate) functions. The full set of API methods for Shadow DOM can be
+found in the [API documentation](./API.md#virtual-dom-utilities), but the general
+structure for a virtualNode is as follows:
+
+```js
+{
+  actualNode: <HTMLElement>,
+  children: <Array>,
+  shadowId: <String>
+}
+```
+
+- A virtualNode is an object containing an HTML DOM element (`actualNode`).
+- Children contains an array of child virtualNodes.
+- The shadowID indicates whether the node is in an open shadow root and if it is, which one it is inside the boundary.
+
+### Core Utilities
+
+Core Utilities are an internal library that provides aXe with functionality used throughout its core processes. Most notably among these are the queue function and the DqElement constructor.
+
+#### ARIA Lookup Tables
+
+axe.commons.aria provides a namespace for ARIA-related utilities, including a lookupTable for attributes and roles.
+
+- `axe.commons.aria.lookupTable.attributes`
+- `axe.commons.aria.lookupTable.globalAttributes`
+- `axe.commons.aria.lookupTable.role`
+
+#### Common Utility Functions
+
+In addition to the ARIA lookupTable, there are also utility functions on the axe.commons.aria and axe.commons.dom namespaces:
+
+- `axe.commons.aria.implicitRole` - Get the implicit role for a given node
+- `axe.commons.aria.label` - Gets the accessible ARIA label text of a given element
+- `axe.commons.dom.isVisible` - Determine whether an element is visible
+
+#### Queue Function
+
+The queue function creates an asynchronous "queue", list of functions to be invoked in parallel, but not necessarily returned in order. The queue function returns an object with the following methods:
+
+- `defer(func)` Defer a function that may or may not run asynchronously
+- `then(callback)` The callback to execute once all "deferred" functions have completed. Will only be invoked once.
+- `abort()` Abort the "queue" and prevent `then` function from firing
+
+#### DqElement Class
+
+The DqElement is a "serialized" `HTMLElement`. It will calculate the CSS selector, grab the source outerHTML and offer an array for storing frame paths. The DqElement class takes the following parameters:
+
+- `Element` - `HTMLElement` The element to serialize
+- `Spec` - `Object` Properties to use in place of the element when instantiated on Elements from other frames
+
+```js
+var firstH1 = document.getElementByTagName('h1')[0];
+var dqH1 = new axe.utils.DqElement(firstH1);
+```
+
+Elements returned by the DqElement class have the following methods and properties:
+
+- `selector` - `string` A unique CSS selector for the element
+- `source` - `string` The generated HTML source code of the element
+- `element` - `DOMNode` The element which this object is based off or the containing frame, used for sorting.
+- `toJSON()` - Returns an object containing the selector and source properties
+
+## Virtual DOM APIs
+
+Note: You shouldn’t need the Shadow DOM APIs below unless you’re working on the axe-core
+engine, as rules and checks already have `virtualNode` objects passed in. However, these APIs
+will make it easier to work with the virtual DOM.
+
+### API Name: axe.utils.getFlattenedTree
+
+#### Description
+
+Recursvely return an array containing the virtual DOM tree for the node specified, excluding comment nodes
+and shadow DOM nodes `<content>` and `<slot>`. This method will return a flattened tree containing both
+light and shadow DOM, if applicable.
+
+#### Synopsis
+
+```js
+var element = document.body;
+axe.utils.getFlattenedTree(element, shadowId);
+```
+
+#### Parameters
+
+- `node` – HTMLElement. The current HTML node for which you want a flattened DOM tree.
+- `shadowId` – string(optional). ID of the shadow DOM that is the closest shadow ancestor of the node
+
+#### Returns
+
+An array of objects, where each object is a virtualNode:
+
+```js
+[
+	{
+		actualNode: body,
+		children: [virtualNodes],
+		shadowId: undefined
+	}
+];
+```
+
+### API Name: axe.utils.getNodeFromTree
+
+#### Description
+
+Recursively return a single node from a virtual DOM tree. This is commonly used in rules and checks where the node is readily available without querying the DOM.
+
+#### Synopsis
+
+```js
+axe.utils.getNodeFromTree(axe._tree[0], node);
+```
+
+#### Parameters
+
+- `vNode` – object. The flattened DOM tree to fetch a virtual node from
+- `node` – HTMLElement. The HTML DOM node for which you need a virtual representation
+
+#### Returns
+
+A virtualNode object:
+
+```js
+{
+  actualNode: div,
+  children: [virtualNodes],
+  shadowId: undefined
+}
+```
+
+## Test Utilities
+
+All tests must support open Shadow DOM, so we created some test utilities to make this easier.
+
+### Test Util Name: MockCheckContext
+
+Create a check context for mocking and resetting data and relatedNodes in tests.
+
+#### Synopsis
+
+```js
+describe('region', function() {
+	var fixture = document.getElementById('fixture');
+
+	var checkContext = new axe.testUtils.MockCheckContext();
+
+	afterEach(function() {
+		fixture.innerHTML = '';
+		checkContext.reset();
+	});
+
+	it('should return true when all content is inside the region', function() {
+		assert.isTrue(checks.region.evaluate.apply(checkContext, checkArgs));
+		assert.equal(checkContext._relatedNodes.length, 0);
+	});
+});
+```
+
+#### Parameters
+
+None
+
+#### Returns
+
+An object containg the data, relatedNodes, and a way to reset them.
+
+```js
+{
+  data: (){},
+  relatedNodes: (){},
+  reset: (){}
+}
+```
+
+### Test Util Name: shadowSupport
+
+Provides an API for determining Shadow DOM v0 and v1 support in tests. For example: PhantomJS doesn't have Shadow DOM support, while some browsers do.
+
+#### Synopsis
+
+```js
+(axe.testUtils.shadowSupport.v1 ? it : xit)(
+	'should test Shadow tree content',
+	function() {
+		// The rest of the shadow DOM test
+	}
+);
+```
+
+#### Parameters
+
+None
+
+#### Returns
+
+An object containing booleans for the following Shadow DOM supports: `v0`, `v1`, or `undefined`.
+
+### Test Util Name: fixtureSetup
+
+Method for injecting content into a fixture and caching the flattened DOM tree (light and Shadow DOM together).
+
+#### Synopsis
+
+```js
+it(
+	'should return true if there is only one ' +
+		type +
+		' element with the same name',
+	function() {
+		axe.testUtils.fixtureSetup(
+			'<input type="' +
+				type +
+				'" id="target" name="uniqueyname">' +
+				'<input type="' +
+				type +
+				'" name="differentname">'
+		);
+
+		var node = fixture.querySelector('#target');
+		assert.isTrue(check.evaluate.call(checkContext, node));
+	}
+);
+```
+
+#### Parameters
+
+- `content` – Node|String. Stuff to go into the fixture (html or DOM node)
+
+#### Returns
+
+An HTML Element for the fixture
+
+### Test Util Name: checkSetup
+
+Create check arguments.
+
+#### Synopsis
+
+```js
+it('should return true when all content is inside the region', function() {
+	var checkArgs = checkSetup(
+		'<div id="target"><div role="main"><a href="a.html#mainheader">Click Here</a><div><h1 id="mainheader" tabindex="0">Introduction</h1></div></div></div>'
+	);
+
+	assert.isTrue(checks.region.evaluate.apply(checkContext, checkArgs));
+	assert.equal(checkContext._relatedNodes.length, 0);
+});
+```
+
+#### Parameters
+
+- `content` – String|Node. Stuff to go into the fixture (html or node)
+- `options` – Object. Options argument for the check (optional, default: {})
+- `target` – String. Target for the check, CSS selector (default: '#target')
+
+#### Returns
+
+An array with the DOM Node, options and virtualNode
+
+```js
+[node, options, virtualNode];
+```
+
+## Using Rule Generation CLI
+
+Axe provides a CLI for generating the necessary files and configuration assets for authoring a rule.
+
+To invoke the rule generator, run:
+
+```sh
+npm run rule-gen
+```
+
+The CLI acts a wizard, by asking a series of questions related to generation of the rule, for example:
+
+```sh
+- What is the name of the RULE? (Eg: aria-valid): sample-rule
+- Does the RULE need a MATCHES file to be created?: Yes
+- Would you like to create a CHECK for the RULE?: No
+- Would you like to create UNIT test files? Yes
+- Would you like to create INTEGRATION test files? Yes
+```
+
+Upon answering of which the the assets are created in the respective directories.