Skip to content
Get 30+ hours of free content from GitHub Universe! Watch now.

Treat accessibility issues as bugs, not feature requests

Follow Drupal’s lead: Prioritize and systematically squash accessibility bugs.

Artwork: Micha Huigen

Photo of Mike Gifford
CivicActions logo

Mike Gifford // Senior Strategist, CivicActions

The ReadME Project amplifies the voices of the open source community: the maintainers, developers, and teams whose contributions move the world forward every day.

When developers think about accessibility, giant spreadsheets of errors from automated testing tools often come to mind. While these barriers correlate with specific pages or issues, they can feel divorced from the code that the developers are working on. So often, the discussion around how to address these errors boils down to how to conform with legislation like Section 508 in the U.S., or the Web Accessibility Directive in Europe, and nothing more. 

In a complex application, it can seem like accessibility errors are a never-ending list of problems. Attempts to fix them are often short-lived and new barriers keep popping up, leaving teams feeling like they’re playing accessibility whack-a-mole. This tends to be disempowering for the millions of teams developing on GitHub, but even more so for the IT community who depends on those libraries.

Drupal, the popular open source content management system, takes a different approach to removing accessibility barriers, and has been a leader in digital accessibility for over a decade now. Teams in government and education often use Drupal, in part because it helps them achieve their own accessibility requirements. As a Drupal Core Accessibility Maintainer, I’m in a unique position to highlight what our community has accomplished and what efforts are effective. Hopefully our approach will hold some lessons for your own efforts toward greater accessibility.


In this Guide, you will learn:

  1. Elements that shifted Drupal’s culture to prioritize accessibility.

  2. How involving users with disabilities helped us set bigger goals.

  3. That you are not alone, and your approach to addressing accessibility should embrace that.


Accessibility begins with leadership

Clear leadership is one of the big things that has allowed Drupal to address its many accessibility issues over the years. Drupal founder and lead developer Dries Buytaert and the leadership team have clearly prioritized accessibility. They made it obvious early on that accessibility issues needed to be addressed and treated as bugs, not feature requests. Without that clarity, it is unlikely there would have been much progress on digital inclusion. 

Everyone thinks accessibility is a good thing, but not many are willing to delay a major software release for it. Drupal signaled its commitment when it made accessibility a core gate, which has meant months-long delays for Drupal releases because of accessibility issues. People pay attention when this happens. It’s easy to claim that issues will be fixed after the release, but it takes the support of leadership to hold it back. 

Buytaert’s team at Acquia contributes considerably to Drupal Core, and he has hired a number of key staff to work on accessibility issues over the years, helping to fix them early in the development process. If accessibility issues aren’t addressed while new features are being developed, they’ll be less likely to be successfully addressed in the future, when they’re inevitably more fragile and more expensive to implement. 

As a result of leadership’s example, the Drupal community cares about accessibility. This is evident in both our online community and conferences. We invested in accessibility before it became popular. Our success made it a higher priority for leadership to fully embrace. Making it easier for a diverse range of people to participate allows everyone to learn and grow. 

I do think it also helps to have tenacious accessibility leadership. The Drupal community has had a number of Core Accessibility Maintainers, and all of them have provided leadership. As the longest-standing maintainer, I can say quite confidently that so much of what I have learned about accessibility, I learned by engaging with both the Drupal and accessibility communities.

Understand where you are on the accessibility spectrum

When I committed to improving Drupal’s accessibility in 2009, I thought that it would be a fairly simple problem to solve. Drupal was already committed to open standards, as governments around the world were using it. It leverages re-usable templates, which limits the number of places that accessibility issues that arise, making them relatively easy to track down and resolve. Furthermore, complex web forms are managed through a central forms API, again eliminating the need to hunt down random form errors throughout the code. 

Nowadays, it might seem like Drupal is less accessible because there are far more known accessibility issues than there were back in 2009, but that’s only because we’ve gotten better at identifying them. In reality, Drupal is substantially more accessible.

When assessing a project’s accessibility, I often search the issue queue on GitHub for “accessibility.” It isn’t uncommon to find a couple issues, and some projects use GitHub tags to help track them. But while these open issues indicate that a project might be aware of its own accessibility barriers, it’s not sufficient to understand the maturity of its approach to accessibility.

Once I’ve viewed the reported accessibility errors in the issue queue, I will often try to look at the user interface. If a project has a demo, I can easily evaluate it with Microsoft’s open source Accessibility Insights. It can provide a summary of errors that make it easy to replicate. Replication is key to resolving any software bugs. I can then add this to the project’s issue queue for the maintainers to consider. Reporting these errors is just the first step. Developers need to replicate the identified bugs and resolve them. 

An additional challenge for project maintainers is that they often get a single issue with a bunch of unrelated accessibility problems all grouped together. It’s much easier to tackle separate issues bundled by error type: It provides a much more granular and actionable view. You may need to ask the people reporting the issue to create child issues and break them down into pieces that are easier for your team to implement. 

Another issue you might face is having too many accessibility problems to solve right away. The Web Content Accessibility Guidelines (WCAG) cover a wide range of accessibility issues. The WCAG offer a map of best practices, but your users may face a range of barriers—not all of which will have clear solutions to implement. If this is the case for your project, the first step is to orient yourself about what is possible. Progress over perfection, but remember that you should be able to prove that you’re making progress.

Accessibility for all users, not just end users

Starting with Drupal 7, more than a decade ago now, we decided to treat WCAG bugs on the back end the same way we do on the front end. We wanted to ensure that someone with a disability could not only read content on Drupal, but also write, edit, and administer it. This wasn’t an arbitrary decision. Rather, Drupal’s first Core Accessibility Maintainer, a blind developer, advocated for it. With over a million instances of Drupal around the world, and with 25% of the population having some form of disability, this allowed an even larger audience of creators to use Drupal.

By Drupal 8, we became one of the first publishing tools to implement the W3C’s Authoring Tool Accessibility Guidelines (ATAG) 2.0, which it released in 2015. ATAG is often overlooked, but has an important role in creating WCAG compliant content. It has two parts.

First, it requires that the authoring interface comply with WCAG. While only a quarter of people have a permanent disability, practically all of us will have temporary or situational disabilities. This includes our authors, so they cannot be overlooked.

Second, ATAG helps authors create more accessible content. This is huge, because we know that so many accessibility issues are added by non-technical content authors. We cannot assume that content creators have a thorough understanding of WCAG 2.1 AA requirements. Instead, they should be given defaults that encourage accessibility best practices. 

When to use existing accessibility best practices vs. when to build your own

In many cases, accessibility best practices have already been well-defined. Often, it’s just a matter of finding an example that’s already been published and tested. There are so many terrific libraries out there to build on that have demonstrated which semantic patterns work best with current browsers and assistive technologies. 

However, identifying and testing best practices is time-consuming. Unfortunately, we can’t always find solutions that work. In these cases it’s necessary to create new solutions.

For example, when we realized that hidden text was a problem for assistive technology, we developed a strategy for content that was hidden, visible on focus, and visible only to screen readers. Later, when the HTML 5 Boiler Plate popularized a similar approach, we aligned with that standard. 

In other cases we’ve struggled to find workable solutions. For example, we ran into problems with the drag/drop interface which was built into the admin interface. Drupal’s drag/drop interface provided a visual means to move content in two dimensions, but it is a challenge to represent this for screen readers, which have a linear audio interface. Our solution was to allow a button to expose the hierarchy, so anyone could edit it using a simple web form. The solution that we implemented for drag/drop works, but isn’t very elegant. We still need robust accessible examples for visually organizing content that are more accessible for everyone. 

We’re also still looking to improve the ways we present error messages to assistive technology users. Web forms are particularly challenging, as they often have accessibility issues even before you have to account for errors.

This is where the open source community can help. Innovations can jump between projects quite quickly. Are there examples of code which have been developed and tested by other open source communities you can use? 

Accessibility must be seen as a journey. We have dramatically improved the accessibility of Drupal, but there is still room to improve. Fortunately, because Drupal is open source, others will be able to build on our work and further raise the bar on inclusion. 

Accessibility is a spectrum: Start where you are

The most important thing in your inclusion journey is to start where you are. There are so many things to learn and different ways that you can become a better developer. One way is to invest in learning more about semantic HTML, which can convey more meaning for assistive technologies than CSS markup. You will not only benefit, it will benefit the people around you and the future software you build. 

The time to begin is now. There is no shortage of free tools and resources that you can leverage—including Drupal. Examples of open source communities who have dramatically improved their accessibility abound. Most importantly, if your project is being actively developed, it is easier to fix accessibility issues today than it will be in six months. 

If you value accessibility but aren’t sure where to begin, consider starting with Drupal. It may not meet all of your requirements, but we have spent more than a decade finding ways to improve our accessibility. No matter what framework you end up using for your final project, there will be good practices to emulate. 

You might be looking at your project and seeing a mountain of work to make it accessible. This is alright, and is perhaps to be expected. To this day, Drupal still has hundreds of issues outstanding in the issue queue, and many thorny challenges yet to tackle. But we’re always improving, and so can you. 

Remember that you are on a journey, and be comfortable knowing that there will always be opportunities for improvement. There is a great deal to learn about digital accessibility, but there are so many open source resources that you can learn from and contribute to. Every maintainer, contributor, and organization can help move the needle. Just like how a journey of a thousand miles begins with a single step, your first step is to make your project just a little bit more accessible than it is right now.

Mike Gifford is a senior strategist at CivicActions and a thought leader on digital accessibility in the public sector. He is also a W3C Invited Expert and recognized authoring tool accessibility expert. Previously, he was the founder and president of OpenConcept Consulting Inc., a web development agency specializing in building open source solutions for the open web. Mike has spearheaded accessibility improvements in Drupal since 2008, and has served as a Drupal Core Accessibility Maintainer since 2012. As a long-term environmentalist, he finds ways to integrate his passions for the web and the planet. His most significant contributions have been in the development of the Sustainable Web Manifesto and adding an open source perspective to Tim Frick’s book Designing for Sustainability.

About The
ReadME Project

Coding is usually seen as a solitary activity, but it’s actually the world’s largest community effort led by open source maintainers, contributors, and teams. These unsung heroes put in long hours to build software, fix issues, field questions, and manage communities.

The ReadME Project is part of GitHub’s ongoing effort to amplify the voices of the developer community. It’s an evolving space to engage with the community and explore the stories, challenges, technology, and culture that surround the world of open source.

Follow us:

Nominate a developer

Nominate inspiring developers and projects you think we should feature in The ReadME Project.

Support the community

Recognize developers working behind the scenes and help open source projects get the resources they need.

Thank you! for subscribing