You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+40Lines changed: 40 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,6 +21,46 @@ The files in this project are formatted by [Prettier](https://prettier.io/) and
21
21
npm run eslint
22
22
```
23
23
24
+
### When to use HTMLElement vs Virtual Node
25
+
26
+
Axe-core uses an internal copy of the HTML page for most things internal to axe-core (called the Virtual Tree). Each HTML element on the page has an equivalent [Virtual Node](./lib/core/base/virtual-node) element, which allows us to cache or normalize information about the HTML element without mutating the actual DOM node.
27
+
28
+
Typically we use the Virtual Node when possible, but understand that's not always possible (such as accessing DOM only APIs like `getRootNode` or `getBoundingClientRect`). Furthermore, any function within the [utils directory](./lib/core/utils/) should not use Virtual Nodes. The reason for this is that using Virtual Nodes requires that axe first be [setup](./lib/core/public/setup.js) and create the Virtual Tree. For the most part, util functions are functions that can be run when no Virtual Tree exists.
29
+
30
+
### Directory Structure
31
+
32
+
Axe-core
33
+
34
+
-`standards` - Data objects of the HTML, WCAG, and ARIA standards and specs.
35
+
-`core/base` - Defines many of the internal object structures for axe-core (rules, checks, virtual node, etc.).
36
+
-`core/imports` - Polyfills or imports from node modules.
37
+
-`core/public` - Functions for how axe is run or configured.
38
+
-`core/reporters` - The different reporters that configure what data is reported from a run.
39
+
-`core/utils` - Utility functions that can be run without needing to set up the Virtual Tree.
40
+
-`commons/aria` - Functions that are used to validate ARIA spec or implement ARIA calculations (role, value, etc.).
41
+
-`commons/color` - Functions that are used to calculate the foreground or background color of an element.
42
+
-`commons/dom` - Functions that access information about the page, DOM, nodes, or its visual state.
43
+
-`commons/forms` - Functions for helping with forms and their associated inputs.
44
+
-`commons/matches` - Functions used to match a virtual node against a special matcher object.
45
+
-`commons/math` - Math functions mainly used for target size and position calculations.
46
+
-`commons/standards` - Functions for querying information from `standards`.
47
+
-`commons/tables` - Functions for helping with data tables.
48
+
-`commons/text` - Functions for calculating the accessible name of an element and handling strings or text related attributes.
49
+
-`rules` - JSON metadata files for each axe-core rule as well as their associated matches functions.
50
+
-`checks` - JSON metadata files for each axe-core check as well as their associated evaluate functions.
51
+
52
+
### Import Requirements
53
+
54
+
Which functions can be imported and how they can be imported depends on where you are trying to import them from. The following is a list of directories and their import restrictions:
55
+
56
+
-`standards` - Shouldn't use imports as they are just hard coded data objects.
57
+
-`core/utils` - Can import other `core/utils`, `core`, `core/base`, or `standards` functions by direct file path (no import from index files).
58
+
-`core/public` - Can import other `core/public` by direct file path, or any import allowed by `core/utils` by direct file path.
59
+
-`core/imports` - The only files allowed to import from node modules, but shouldn't import from any other directory.
60
+
-`core/reporters` Can import from `core/utils` by import from index files.
61
+
-`commons` - Can import other `commons` by direct file path, or any import allowed by `core/utils` by import from index files.
62
+
-`checks` and `rules` - Can import from any directory by import from index files.
63
+
24
64
### Shadow DOM
25
65
26
66
For any proposed changes to rules, checks, commons, or other APIs to be accepted in axe-core, your code must support open Shadow DOM. See [API.md](./doc/API.md) and the [developer guide](./doc/developer-guide.md) for documentation on the available methods and test utilities. You can also look at existing tests for examples using our APIs.
0 commit comments