Add guides for Cypress Accessibility

docs/accessibility/changelog.mdx

@@ -7,6 +7,10 @@ sidebar_position: 200
 
 # Changelog
 
+## Week of 11/11/2024
+
+- A "Share Issue" button has been added to the element details section for each reported rule violation. This allows for easily copying the key details and related links for a particular issue into your clipboard to add to a message or to a ticket in your issue tracking system.
+
 ## Week of 10/28/2024
 
 - Our [Axe Core® versioning policy](/accessibility/core-concepts/how-it-works#Axe-Core-updates) has been published, providing a 30-day buffer between any Axe Core® releases and the adoption of those releases in Cypress Cloud.

docs/accessibility/guides/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Guides",
+  "position": 70
+}

docs/accessibility/guides/accessibility-automation.mdx

@@ -0,0 +1,43 @@
+---
+title: Accessibility automation principles
+sidebar_position: 80
+---
+
+This guide describes some general ideas that are relevant to Cypress Accessibility, but are also somewhat shared among accessibility automation tools of any kind.
+
+## What it means to fix all Axe Core® violations {#what-it-means-to-fix-all-axe-core-violations}
+
+Cypress Accessibility runs Axe Core® checks on every significant state and variation of the applications you test with Cypress. This kind of automation can catch up to [57% of issues that would appear in a manual audit](https://www.deque.com/blog/automated-testing-study-identifies-57-percent-of-digital-accessibility-issues/), but it does not replace the human judgment that is applied during an audit. Auditors test a wide variety of scenarios and technologies in a way that would be impossible to fully automate.
+
+It helps to think of accessibility at three levels. The first is “basic usability”. Paying attention to issues reported by Cypress and Axe Core® should help you to this point. This is the threshold at which a disabled user is likely to be able to make substantial progress through the application, but may still hit major barriers or usability issues. If your contact forms and issue reporting systems are accessible, you will be able to learn about these problems from actual users.
+
+The second level of accessibility is full conformance with all Web Content Accessibility Guidelines (WCAG) success criteria. As mentioned above, more than half of issues reported in manual audits can be reported and caught early with Axe Core ®automation. Conformance with the WCAG is often the standard set by legislation and regulation related to web accessibility. If your goal is regulatory compliance, this is the bar. No generic automation tool can “prove” compliance with this standard, it **requires** human assessment.
+
+The third level, and the true goal of many accessibility programs, is a good user experience. This needs to be validated by actual disabled users who are daily users of assistive technology. It’s entirely possible to have a website that passes the first two levels, and still offers a poor user experience.
+
+Accessibility is about communicating the nature and structure of the application, and the available actions and information, in a way that allows disabled users to independently understand the interface and complete all tasks. The foundational [POUR principles](https://www.24a11y.com/2019/pour-the-foundation-first/) of the WCAG \- that software must be Perceivable, Operable, Understandable and Robust \- are bigger than any specific set of test plans or static checks. While Axe Core® tell us about many genuine accessibility barriers, it is important to leverage that information into making good decisions about accessibility and providing a truly equal experience.
+
+## False positives
+
+False positives are always a risk in any automated scans. Both Cypress Accessibility and Axe Core® are designed in a way that minimizes them, but it’s always possible that there will be some violations in the report that you recognize as invalid and would rather exclude, or are genuinely incorrect.
+
+While false positives are rare, if in doubt, use the “provide feedback” button to alert us to something you see as a false positive and we can work on diagnosing and solving the issue from our side.
+
+### Genuine false positives
+
+There are two main possible sources of genuine false positive results:
+
+1. The check was run on an **invalid** **state** \- for example a partially hydrated DOM \- that no user would ever see. These are scenarios that Cypress can account for in the product if they are reported.
+2. The state tested was correct but Axe Core® reported a violation that it shouldn’t have, as a result of a bug or missing check. Since Axe Core® is an open-source product, if and when we encounter bugs, we can open issues in the project and even make pull requests if needed.
+
+### Loading states
+
+There’s another scenario that can present as a potential false positive: legitimate user-facing loading states. These are situations where some data is pending in your application.
+
+It might be tempting to say “this state shouldn’t be captured, it’s not fully loaded” \- but in reality, these types of “pending” states are valid, and often contain visual information like loading spinners, UI skeletons, and progress bars which should be accessible themselves, so the user knows what data is loading. It’s also possible that the data doesn’t come in at all, or is very slow, and a user needs to figure out what is happening and what they can do, so the application needs to remain in a fully accessible, usable condition even if data is pending.
+
+In general it’s a good idea in front-end development to “make impossible states impossible”, and in doing so you can follow the accessibility principle of Robustness (the last of the 4 POUR principles mentioned above), while also making it much less likely that an invalid state is possible to reach in Cypress in the first place. This can also have a beneficial effect on the overall stability of your tests.
+
+### Assistive technology support
+
+Certain accessibility techniques are not fully supported by all assistive technologies like screen readers or voice control software. Axe Core® accounts for this. The software and operating systems tested against are listed in their [Accessibility Supported document](https://github.com/dequelabs/axe-core/blob/develop/doc/accessibility-supported.md). For example: it can seem like a false positive from Axe Core® if a failing technique used in your code appears to work correctly in a certain screen reader, browser and operating system combination that you test with. But if it does not have sufficient accessibility support in commonly used technology configurations, Axe Core® will intentionally fail that technique, allowing you to switch to something with better support.

docs/accessibility/guides/accessibility-automation/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Accessibility automation",
+  "collapsible": true,
+  "collapsed": false
+}

docs/accessibility/guides/blocking-pull-requests.mdx

@@ -0,0 +1,60 @@
+---
+title: Blocking pull requests and setting policies
+sidebar_position: 40
+---
+
+Cypress Accessibility reports are generated on the server in Cypress Cloud, based on artifacts uploaded by the test runs. Because of this, there is no impact to your actual Cypress test execution, in terms of performance or anything else - including failing the Cypress run due to accessibility violations.
+
+## Using the Results API
+
+The Cypress Accessibility Results API provides access to accessibility results after the run is completed, so that you can implement patterns like blocking a pull request or sending out alerts based on specific accessibility criteria. This is done by adding a separate accessibility verification step to your CI pipeline, and using a helper function provided by Cypress to automatically request the report for the appropriate Cypress run based on the build context. The example below shows how this can look in GitHub Actions when there is an accessibility failure based on your own chosen policy:
+
+<DocsImage
+  src="/img/accessibility/guides/github-actions-a11y-block.png"
+  width="75%"
+  alt="On the left hand side, a list of Github Actions jobs is presented related to building, testing and deploying a website. Everything has a green checkmark except the `verify-accessibility-results` job, and the 'test' job that is its parents. On the right hand side we see the terminal output for that job which warns us that the 'button-name' rule has been broken, and that it was previously passing."
+  noBorder={true}
+/>
+
+## Implementing a status check
+
+The API gives you full flexibility to examine the results and react to it in whatever way you need to. It also provides a signal that can be used in status checks on Pull Requests. Here is an example where the accessibility verification step is passing:
+
+<DocsImage
+  src="/img/accessibility/guides/status-check.png"
+  width="75%"
+  alt="An example list of GitHub Status Checks including a passing `verify-accessibility-results` check"
+  noBorder={true}
+/>
+
+## Implementing a policy in the verification step
+
+The [Results API Documentation](/accessibility/results-api) describes the capabilities of the API in more detail, but here is a simplified example of how to use the API to implement the "no new failing accessibility rules" policy shown above.
+
+```js
+const { getAccessibilityResults } = require('@cypress/extract-cloud-results')
+
+// define your known failing rules
+const rulesWithExistingViolations = [
+  'button-name',
+  ...
+]
+
+// call the API
+getAccessibilityResults()
+  .then((results) => {
+    // compare the accessibility results with your acceptable standard
+    const newRuleViolations = results.rules.filter((rule) => {
+    return !rulesWithExistingViolations.includes(rule.name)
+   })
+
+   if (newRuleViolations.length > 0) {
+    // based on the standard, trigger any side effect you like, such as failing the step
+    throw new Error(
+      `${newRuleViolations.length} rule regressions were introduced and must be fixed.`
+    )
+  }
+})
+```
+
+This process of examining the results and then deciding the appropriate response gives you the most flexibility in terms of how exactly you want to force a stopping point or specific reaction based on the contents. You have access to the results as well as any context needed from the CI environment, such as tags, to implement the correct response to any specific result values.

docs/accessibility/guides/improving-accessibility.mdx

@@ -0,0 +1,60 @@
+---
+title: Improving accessibility
+sidebar_position: 20
+---
+
+In this section we'll discuss how to break down the data in your accessibility report and make a plan for remediation.
+
+<DocsImage
+  src="/img/accessibility/guides/a11y-standards.png"
+  alt="A list of accessibility rules where some are passing and failing. Two major sections are identified - the passing rules as 'Your current standard', and the failing rules as 'Your issues to address'. Within the failing rules list, 2 rules are called out as 'Your next tasks' because they have the smallest count of elements failing the rule."
+  noBorder={true}
+/>
+
+## Starting from Scratch
+
+When you first start to use Cypress Accessibility, you may be testing a legacy application with many existing accessibility violations. The [Accessibility tab for a run](/accessibility/core-concepts/run-level-reports) can show multiple violations detected on dozens or hundreds of pages in your application. The number of failing elements and page or component snapshots available might be overwhelming, making it difficult to know where to start.
+
+In this situation, the first step is to understand some of the key variables and how they are related within your organization. The kinds of things to consider are:
+
+- your goals for the accessibility of the application
+- your timeline for making it accessible
+- the available resources for remediation
+- what code is likely to change in the near future, where accessibility can be included in designs and requirements
+- the consequences, risks, and costs of remaining inaccessible
+
+These factors will help you find the right strategy for engaging with the results displayed in your accessibility reports. While incremental accessibility efforts by designers and engineers are never wasted, the best outcomes come from an overall organizational commitment to ship accessible software, which requires investment from all departments, so understanding your organization's stance on accessibility and who needs to be in the conversation is also helpful.
+
+If your organization or team is newer to accessibility, you are likely to find plenty of issues reported by Axe Core® in Cypress Cloud. Many of the issues in your first report may relate to concepts that are new, such as [ARIA attributes](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) or [invalid nesting of interactive controls](https://dequeuniversity.com/rules/axe/4.2/nested-interactive). Since it will be impossible to fix all issues overnight, we recommend finding some low-hanging fruit as a starting point. This can help your team build confidence by getting some wins on the board, and teach them the overall idea of how accessibility problems get fixed.
+
+### Good low-hanging fruit
+
+Some of the easiest, and most valuable issues to tackle first come from [WCAG SC 4.2.1 \- Name, role, value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html). This is the part of the Web Content Accessibility Guidelines that’s concerned with making sure interactive controls have appropriate labels for all users. In general, your app is likely to have some violations in this category, and Axe-Core® tends to flag these as Critical or Serious, because the lack of a label usually makes it difficult or impossible for some users to know what something does in a user interface.
+
+Within the “Name, role, value” success criterion, the [`button-name`](https://dequeuniversity.com/rules/axe/4.7/button-name) rule in Axe Core® (“Buttons must have discernible text”) is a great place to start. Icons being used as buttons are common in modern user interfaces and they are often missing descriptive text content for screen reader users, which directly impacts their ability to understand the purpose and effect of the button and independently complete tasks in your application.
+
+This rule, and others like it, are good starting points because the rule is easy to understand and easy to fix. Since the solution is purely a code update to add the missing label text to buttons, this category of rule requires little or no coordination across departments or teams to address. These types of issues are also straightforward to demonstrate and validate even for beginners with a screen reader.
+
+Existing code failing the button-name rule can usually be remediated pretty quickly, as long as it is clear what the correct text label is for a given control. And when it comes to new code, this text label content is also easy to add to discussions in the design and requirements stages of the development cycle, shifting the accessibility conversation left.
+
+Since every violation in Cypress is linked to a Deque University page with details about the nature of the problem and how to fix it, all the needed context is available, even to engineers who may be new to the topic of accessiblity in general, or to a specific violation.
+
+Even if your first rule is not “Buttons must have discernible text”, we suggest finding one with a similarly small amount of coordination or understanding needed to fix, so the team can experience success as quickly as possible.
+
+### Finding low-hanging fruit with Cypress
+
+Cypress Accessibility generates a separate report for each page and component tested in a run. It’s also possible to see all accessibility rules that failed across the entire run. The rules-first approach is useful when finding low-hanging fruit. The rules with the smallest element count are the closest to being fully fixed, and removed from the report. If, at the “All Views” level, there’s not a good rule with a low element count, the next step is to focus on just a single View in the report. You might not be able to fix all buttons across the application, for example, but maybe you can pick a single page and fix just the issues on that specific page.
+
+### Setting the goal
+
+Your goal is to get your target rule’s failing elements down to zero for your chosen scope. That scope can be a specific page, a set of pages, or the entire application. Seeing that rule disappear from a report provides a clear finish line for you and your team. It also provides time to assess the impact of the changes.
+
+Often, due to the componentized nature of modern web apps, fixing an issue in one place has knock-on benefits around the app. Even if you focused on a narrow scope, your changes may still have had a wider impact, so remember: it’s fine for these first goals to be small at first. In fact, it’s preferable.
+
+### Iterating towards success {#iterating-towards-success}
+
+By setting a reasonable goal to understanding and fix specific rules scoped to defined areas of the application being tested, your team can make incremental progress on accessibility without becoming overwhelmed. With support from the Deque University “Learn More” links embedded into the reports, your team can specialize in one rule at a time, learn the related context, and then go deeper on more complicated or debatable topics.
+
+Given enough capacity, as dictated by the urgency of accessibility remediation combined with other business constraints, you will eventually solve all issues that are reported with Cypress Accessibility, and be well on your way to a more usable, accessible experience.
+
+If you are interested in using Cypress to detect and prevent regressions in the rules that you already have passing, you can learn how to use the Results API to do this in our [Blocking Pull Requests Section](/accessibility/guides/blocking-pull-requests).