Skip to main content
Cypress Accessibility+ Add-on

Improve accessibility

This guide explains how to break down accessibility reports and create a focused plan for remediation using Cypress Accessibility.

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.

Starting from Scratch​

If you're beginning with a legacy application that has many accessibility issues, Cypress Accessibility provides actionable insights to help you prioritize fixes. Use the Accessibility tab for a run to identify violations across pages and components. Although the volume of issues might seem overwhelming, focusing on key factors can guide your approach:

  • Goals: Define your accessibility objectives.
  • Timeline: Establish a realistic timeline for improvements.
  • Resources: Assess the resources available for remediation.
  • Future Code Changes: Focus on areas of the codebase likely to evolve.
  • Risk Assessment: Consider the risks and costs of remaining inaccessible.

Effective remediation often requires collaboration across departments, emphasizing the importance of an organization-wide commitment to accessibility, 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're likely to find plenty of issues reported by Axe Core® in Cypress Accessibility. Many of the issues in your first report may relate to concepts that are new, such as ARIA attributes or invalid nesting of interactive controls. 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 accessibility issues are easier to address but have a significant impact. Consider issues related to WCAG SC 4.2.1 - Name, role, value, which ensures interactive controls are appropriately labeled. Violations in this category often:

  • Appear frequently in applications.
  • Are flagged as Critical or Serious by Axe Core®.
  • Directly impact usability for screen reader users.

Example: "Buttons Must Have Discernible Text"​

A common issue in modern interfaces is unlabeled icons used as buttons. The button-name rule, which ensures buttons have descriptive text, is an ideal starting point because:

  • Adding a label is a simple code update.
  • Proper labels improve usability for all users.
  • Fixes typically don't require cross-team involvement.
  • Straightforward to validate 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 accessibility.

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.

Setting achievable goals​

Define a clear objective for each effort, such as fixing all violations of a specific rule within a defined scope. For example:

  • View Focused: Address all rule violations on a single page or component.
  • Rule Focused: Resolve a single rule violation across multiple pages or the entire application.

Achieving these milestones provides a clear finish line for you and your team. It also provides time to assess the impact of the changes. Often, fixing one issue can cascade changes across your application, especially in componentized architectures: it's fine for these first goals to be small at first. In fact, it's preferable.

Iterating towards success​

Incremental progress is key to long-term accessibility improvements. By focusing on manageable goals, your team can:

  • Gain expertise in specific accessibility rules.
  • Build workflows for preventing future regressions.
  • Gradually raise the accessibility standard across your projects.

With support from Deque University's "Learn More" links in the reports, even teams new to accessibility can learn the related context and confidently address violations.

For guidance on preventing regressions and enforcing accessibility policies, explore our Blocking Pull Requests Section.

Contents