From 717963aa5eaed08ee513e5288c1a8636b8e2822d Mon Sep 17 00:00:00 2001 From: Jeremy M Rivera Date: Wed, 20 Nov 2024 17:20:51 -0500 Subject: [PATCH] Several grammatical/syntax updates for consistency and clarity --- README.md | 4 ++-- doc/API.md | 22 +++++++++++----------- doc/accessibility-supported.md | 4 ++-- doc/act-rules-format.md | 10 +++++----- doc/backwards-compatibility-doc.md | 8 ++++---- doc/check-message-template.md | 10 +++++----- doc/code-submission-guidelines.md | 16 ++++++++-------- doc/context.md | 8 ++++---- doc/frame-messenger.md | 12 ++++++------ doc/issue_impact.md | 6 +++--- doc/plugins.md | 8 ++++---- doc/release-and-support.md | 12 ++++++------ doc/rule-development.md | 14 +++++++------- doc/rule-proposal.md | 6 +++--- doc/run-partial.md | 8 ++++---- doc/standards-object.md | 8 ++++---- package-lock.json | 2 +- test/node/package-lock.json | 6 ++++++ 18 files changed, 85 insertions(+), 79 deletions(-) create mode 100644 test/node/package-lock.json diff --git a/README.md b/README.md index 635a1d93ee..57b726eaf5 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Axe is an accessibility testing engine for websites and other HTML-based user in ## The Accessibility Rules -Axe-core has different types of rules, for WCAG 2.0, 2.1, 2.2 on level A, AA and AAA as well as a number of best practices that help you identify common accessibility practices like ensuring every page has an `h1` heading, and to help you avoid "gotchas" in ARIA like where an ARIA attribute you used will get ignored. The complete list of rules, grouped WCAG level and best practice, can found in [doc/rule-descriptions.md](./doc/rule-descriptions.md). +Axe-core has different types of rules, for WCAG 2.0, 2.1, 2.2 on level A, AA and AAA as well as a number of best practices that help you identify common accessibility practices like ensuring every page has an `h1` heading, and to help you avoid "gotchas" in ARIA like where an ARIA attribute you used will get ignored. The complete list of rules, grouped WCAG level and best practice, can be found in [doc/rule-descriptions.md](./doc/rule-descriptions.md). With axe-core, you can find **on average 57% of WCAG issues automatically**. Additionally, axe-core will return elements as "incomplete" where axe-core could not be certain, and manual review is needed. @@ -65,7 +65,7 @@ Axe was built to reflect how web development actually works. It works with all m - It's actively supported by [Deque Systems](https://www.deque.com), a major accessibility vendor. - It integrates with your existing functional/acceptance automated tests. - It automatically determines which rules to run based on the evaluation context. -- Axe supports in-memory fixtures, static fixtures, integration tests and iframes of infinite depth. +- Axe supports in-memory fixtures, static fixtures, integration tests, and iframes of infinite depth. - Axe is highly configurable. ## Supported Browsers diff --git a/doc/API.md b/doc/API.md index 828fd52778..569d516571 100644 --- a/doc/API.md +++ b/doc/API.md @@ -1,4 +1,4 @@ -# Axe Javascript Accessibility API +# Axe JavaScript Accessibility API ## Table of Contents @@ -49,8 +49,8 @@ This section gives a quick description of how to use the axe APIs to analyze web The axe API can be used as part of a broader process that is performed on many, if not all, pages of a website. The API is used to analyze web page content and return a JSON object that lists any accessibility violations found. Here is how to get started: 1. Load page in testing system -2. Optionally, set configuration options for the javascript API (`axe.configure`) -3. Call analyze javascript API (`axe.run`) +2. Optionally, set configuration options for the JavaScript API (`axe.configure`) +3. Call analyze JavaScript API (`axe.run`) 4. Either assert against results or save them for later processing 5. Repeat for any inactive or non-rendered content after making it visible @@ -58,7 +58,7 @@ The axe API can be used as part of a broader process that is performed on many, ### Overview -The axe APIs are provided in the javascript file axe.js. It must be included in the web page under test, as well as each `iframe` under test. Parameters are sent as javascript function parameters. Results are returned in JSON format. +The axe APIs are provided in the JavaScript file axe.js. It must be included in the web page under test, as well as each `iframe` under test. Parameters are sent as JavaScript function parameters. Results are returned in JSON format. ### Full API Reference for Developers @@ -72,7 +72,7 @@ For a full listing of API offered by axe, clone the repository and run `npm run ### Axe-core Tags -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. +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 has 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. The `experimental`, `ACT`, `TT`, 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`. @@ -182,7 +182,7 @@ In this example, we pass in the WCAG 2 A and AA tags into `axe.getRules` to retr To configure the format of the data used by axe. This can be used to add new rules, which must be registered with the library to execute. -**important**: `axe.configure()` does not communicate configuration calls into iframes. Instead `axe.configure()` must be called with the same argument in each `frame` / `iframe` individually. +**Important**: `axe.configure()` does not communicate configuration calls into iframes. Instead `axe.configure()` must be called with the same argument in each `frame` / `iframe` individually. #### Description @@ -213,7 +213,7 @@ axe.configure({ - `reporter` - Used to set the output format that the axe.run function will pass to the callback function. Can pass a reporter name or a custom reporter function. Valid names are: - `v1` to use the previous version's format: `axe.configure({ reporter: "v1" });` - `v2` to use the current version's format: `axe.configure({ reporter: "v2" });` - - `raw` to return the raw result data without formating: `axe.configure({ reporter: "raw" });` + - `raw` to return the raw result data without formatting: `axe.configure({ reporter: "raw" });` - `raw-env` to return the raw result data with environment data: `axe.configure({ reporter: "raw-env" });` - `no-passes` to return only violation results: `axe.configure({ reporter: "no-passes" });` - `checks` - Used to add checks to the list of checks used by rules, or to override the properties of existing checks @@ -567,7 +567,7 @@ The `resultTypes` option can be used to limit the number of nodes for a rule to After axe has processed all rules normally, it generates a unique selector for all nodes in all rules. This process can be time consuming, especially for pages with lots of nodes. By limiting the nodes to a maximum of one for result types you are not interested in, you can greatly speed up the tail end performance of axe. -Types listed in this option will cause rules that fall under those types to show all nodes. Types _not_ listed will causes rules that fall under one of the missing types to show a maximum of one node. This allows you to still see those results and inform the user of them if appropriate. +Types listed in this option will cause rules that fall under those types to show all nodes. Types _not_ listed will cause rules that fall under one of the missing types to show a maximum of one node. This allows you to still see those results and inform the user of them if appropriate. ```js axe.run( @@ -670,7 +670,7 @@ The results of axe are grouped according to their outcome into the following arr - `passes`: These results indicate what elements passed the rules - `violations`: These results indicate what elements failed the rules - `inapplicable`: These results indicate which rules did not run because no matching content was found on the page. For example, with no video, those rules won't run. -- `incomplete`: Also known as "needs review," these results were aborted and require further testing. This can happen either because of technical restrictions to what the rule can test, or because a javascript error occurred. +- `incomplete`: Also known as "needs review," these results were aborted and require further testing. This can happen either because of technical restrictions to what the rule can test, or because a JavaScript error occurred. Each object returned in these arrays have the following properties: @@ -834,7 +834,7 @@ axe.teardown(); ### API Name: axe.frameMessenger -Set up a alternative communication channel between parent and child frames. By default, axe-core uses `window.postMessage()`. See [frame-messenger.md](frame-messenger.md) for details. +Set up an alternative communication channel between parent and child frames. By default, axe-core uses `window.postMessage()`. See [frame-messenger.md](frame-messenger.md) for details. ### API name: axe.runPartial / axe.finishRun @@ -931,7 +931,7 @@ The top-level document or shadow DOM document fragment This package contains examples for [jasmine](examples/jasmine), [mocha](examples/mocha), [qunit](examples/qunit), and [generating HTML from the violations array](examples/html-handlebars.md). Each of these examples is in the [doc/examples](examples) folder. In each folder, there is a README.md file which contains specific information about each example. -See [axe-webdriverjs](https://github.com/dequelabs/axe-webdriverjs#axe-webdriverjs) for selenium webdriver javascript examples. +See [axe-webdriverjs](https://github.com/dequelabs/axe-webdriverjs#axe-webdriverjs) for selenium webdriver JavaScript examples. ## Section 4: Performance diff --git a/doc/accessibility-supported.md b/doc/accessibility-supported.md index 6585bd0a9a..732fed0857 100644 --- a/doc/accessibility-supported.md +++ b/doc/accessibility-supported.md @@ -6,7 +6,7 @@ In order to adhere to the manifesto and at the same time be useful to developers Accessibility supported means that in order for a technique to pass, it must work in some predefined set of browsers and assistive technologies. For axe-core this means that for a screen reader, browser, or environment to be added to the list of supported combinations, the following two criteria must be met: -1. Be used by more than 1% of users (currently extrapolated from the [WebAims Screen Reader User Survey](https://webaim.org/projects/screenreadersurvey10/#browsercombos)) +1. Be used by more than 1% of users (currently extrapolated from the [WebAim Screen Reader User Survey](https://webaim.org/projects/screenreadersurvey10/#browsercombos)) 1. Introduce new coverage for a screen reader, browser, or environment not currently accessibility supported We currently test the following AT combinations for support @@ -32,6 +32,6 @@ In addition, we disallow invalid attributes starting with `aria-` and invalid at ## 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 there are best practices that significantly improve the usability of an 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 controversial and the rules we have represent Deque's opinion on what constitutes a best practice. diff --git a/doc/act-rules-format.md b/doc/act-rules-format.md index 1ff49a7ea7..9fec563685 100644 --- a/doc/act-rules-format.md +++ b/doc/act-rules-format.md @@ -1,6 +1,6 @@ # 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/). +Deque Systems is one of the 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: @@ -9,9 +9,9 @@ There are two ways a rule written in the axe-core rule format can be transformed 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 +2. Add an `assumptions` section, including 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 +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: @@ -19,7 +19,7 @@ This method is useful for rules with a small number of checks. - `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. +8. Replace the `tags` section with an `Accessibility Requirements`. The requirements can be determined based on the `wcag###` tags. ## Method 2: Create a rule group @@ -34,4 +34,4 @@ This method is useful for larger rules with `any` checks. This effectively turns 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. +10. Replace the `tags` section with an `Accessibility Requirements`. The requirements can be determined based on the `wcag###` tags. diff --git a/doc/backwards-compatibility-doc.md b/doc/backwards-compatibility-doc.md index 34d6c90c55..2321b55390 100644 --- a/doc/backwards-compatibility-doc.md +++ b/doc/backwards-compatibility-doc.md @@ -8,7 +8,7 @@ The axe-core API includes: - The selectors generated and included in the node information in the results arrays for any given HTML page - The JSON structures passed into and out of any API functions - Any functions in the `axe.utils` and `axe.commons` collections that are used by one of our standard rules (this document refers to these as the “Public Utils”). This includes use in any of the “matches”, “eval” and “after” functions. -- The implicit function signature of the matches, eval and after functions (the names of the parameters that are passed-to the functions and the values returned by them) +- The implicit function signature of the matches, eval and after functions (the names of the parameters that are passed to the functions and the values returned by them) ## What is not included in the public axe-core API? @@ -20,7 +20,7 @@ We guarantee that the API signatures and the return values of functions will not In a minor release, we may change the implementation of Public Utils to fix bugs or improve performance. This means that a call to a Public Util may return a different value across patch versions. -We will not add or remove rules in a patch release. We will not add support for new technologies in a patch release. We will endeavour to return the exact same results across patch releases with the exception of changes that are due to bug fixes. This means that the likelihood of a patch release finding issues on a page that was clean in a previous release is very close to zero but not zero. +We will not add or remove rules in a patch release. We will not add support for new technologies in a patch release. We will endeavor to return the exact same results across patch releases with the exception of changes that are due to bug fixes. This means that the likelihood of a patch release finding issues on a page that was clean in a previous release is very close to zero but not zero. In a minor release, we may add support for new technologies in the Public Utils or in existing rules and we may add or disable rules. We may also change an experimental rule to become a standard rule (essentially equivalent to adding rule). This means that pages that did not return violations in a particular minor release may return violations in a subsequent release. Rule tags, including the "wcag\*" tags, and whether or not something is reported as best-practice can be changed in minor releases. @@ -44,7 +44,7 @@ Major releases may remove rules. | APIs removed | May be removed (will remove previously deprecated APIs) | Will not be removed | Will not be removed | | **Public Utils** | | | | | Implementation of Public Utils | May change | May change | Will not change | -| New public Utils | May add | May add | Will not add | +| New Public Utils | May add | May add | Will not add | | **Rules** | | | | | Add rules | May add | May add | Will not add | | Disable or remove rules | May remove (will remove previously deprecated rules) | May disable or remove | Will not disable or remove | @@ -61,7 +61,7 @@ Patch release upgrades can be applied in CI environments with a high degree of c ### Custom Rules -A custom rule configuration (with-or-without custom rules) is guaranteed to run on any newer version that shares the same major version number as the version for which it was created. A custom rule configuration (with-or-without custom rules) is not guaranteed to work with an older version of axe-core than the version for which it was created. +A custom rule configuration (with or without custom rules) is guaranteed to run on any newer version that shares the same major version number as the version for which it was created. A custom rule configuration (with or without custom rules) is not guaranteed to work with an older version of axe-core than the version for which it was created. You can write custom rules that utilize the Public Utils and the parameters that are passed to a check function, secure in the knowledge that the API will not change unless a major version is released. diff --git a/doc/check-message-template.md b/doc/check-message-template.md index 95114474da..ff00dee60b 100644 --- a/doc/check-message-template.md +++ b/doc/check-message-template.md @@ -4,7 +4,7 @@ Axe-core uses a custom template to handle dynamic check messages (messages that ## Simple Message -A simple message is just a string that doesn't use the `data` property. Most checks uses this format. +A simple message is just a string that doesn't use the `data` property. Most checks use this format. ```json { @@ -51,7 +51,7 @@ this.data({ ## Singular and Plural Messages -If the message needs to to know how many items are in the `data` property to determine the type of language to use (singular or plural), you can structure the message to use `singular` and `plural` properties. Use the syntax `${data.values}` to have the message output a comma-separated list of the items (`data.values` is provided by the template code for you). +If the message needs to know how many items are in the `data` property to determine the type of language to use (singular or plural), you can structure the message to use `singular` and `plural` properties. Use the syntax `${data.values}` to have the message output a comma-separated list of the items (`data.values` is provided by the template code for you). ```js // check.js @@ -96,15 +96,15 @@ The messages can still use the syntax `${data.propName}` to access other propert ## Migrating From doT.js Template in Translations -Axe-core use to use doT.js for it's temple library. To migrate from doT.js in a translation file, do the following: +Axe-core formerly used doT.js for it's template library. To migrate from doT.js in a translation file, do the following: - If the message used `{{=it.data}}` or `{{=it.data.propName}}`, change the message to use the syntax `${data}` or `${data.propName}`. ```diff { "messages": { -- "incomplete": "Check that the