All Access: Website Front-End Updates Provide Greater Accessibility for America’s Code
Published in
7 min readAug 27, 2020


Accessibility Button on Computer Keyboard (Credit:GOCMEN, Getty Images)

By Anna Zhang, Coding it Forward Fellow

Last month we celebrated the 30th anniversary of the Americans with Disabilities Act. The landmark legislation sought to guarantee equal access and opportunity for people with disabilities. For many, accessibility means the creation of designated parking spaces or installation of wheelchair-friendly ramps and lifts. But in an increasingly changing world where digital technologies now touch nearly every aspect of our lives — from how we work, learn, and communicate to how we get food and medical services — access within the digital world in addition to the physical world is more important than ever.

When I joined the team in June as a Civic Digital Fellow, I was unfamiliar with web accessibility. In my design and computer science classrooms, I had yet to hear any mention of it. I quickly learned that in addition to the Americans with Disabilities Act, there’s also the 21st Century Integrated Digital Experience Act, which outlines website modernization requirements to improve how the public interacts with government services, and Section 508, which details requirements agencies must meet to ensure that digital tools and information are accessible to individuals with disabilities.

Of course, it is incredibly important that is compliant with these laws. But it’s also crucial that we understand the importance and value of accessibility. Accessibility is often the difference between a person being able to get information and services and being completely excluded from them. is a platform that shares America’s code and is built on the belief that innovation thrives when spaces are open, welcoming, and collaborative. In order to advance this mission, the site needs to be accessible.

Accessibility is an opportunity to build a better platform for everybody.

My project this summer involved integrating the U.S. Web Design System (USWDS) into, allowing the platform to take advantage of the consistent design and development patterns of the USWDS library instead of relying on custom code. In essence, the intent was to embrace the accessibility and usability practices at the core of USWDS while maintaining’s brand identity through the colors and custom typeface.

By following the design principles and user experience guidance of USWDS and updating the custom components of the site with equivalent USWDS components, we were able to create a site that is more accessible and mobile-friendly. This ultimately benefits everyone.

Color Code

For instance, on’s “Projects” page, the data quality score label on each project previously did not meet color contrast requirements. The USWDS color tokens use a grade system to help teams quickly check for color contrast and find accessible color pairings. By using a color pairing that meets color contrast requirements, each project’s data quality score is now readable for those with low vision or color vision deficiency, as well as for those with low contrast sensitivity, which is common among older adults. But this change also has the potential to help all users. Perhaps you’re outside and trying to read in a very bright environment, or even if you don’t have specific visual or environmental conditions, the labels that now meet color contrast requirements are easier to read than they were before.

The data quality score label previously had insufficient color contrast (top left). The updated color pairing has greater color contrast (bottom right).


We replaced the custom-developed main navigation menu of the site using the USWDS header component. The previous main navigation menu for mobile devices did not adapt well on select narrow screens, such as the Galaxy Fold. Some of the controls like the search button and the dropdown arrow for the menu sections were cut off. By using the USWDS header component and refactoring the main navigation menu, the menu became more mobile-friendly and responsive.

In accordance with USWDS header accessibility guidelines, we implemented a skip navigation link so that keyboard and screen reader users could bypass the repetitive navigation menu links and go right to the main content.

Updated navigation bar for the Website.

The Tools of the Trade

From buttons and dropdowns to the grid system and spacing units, we were able to use USWDS throughout the site. Using USWDS helped improve not only accessibility and usability for the site but also code maintainability. In the end, we removed over 40 custom Sass files, and the team no longer needs to maintain the code-gov-style and code-gov-font repositories.

At the time, used two automated tools to test for accessibility: Pa11y and Lighthouse. These tools were able to detect some code structure errors, like whether forms have labels or if images have alt text. After integrating USWDS and fixing these issues, the site achieved 100% on Lighthouse and all URLs passed Pa11y.

The Importance of Manual Testing

While using automated tools to test for web accessibility is a good starting point, I also learned there are limits to automated tools. Automated testing tools can help catch many accessibility issues, but they alone cannot determine if a site is accessible. For instance, automated tools cannot check most dynamic elements, so it can’t really engage with a site as a real user would, and it’s also context insensitive. By integrating manual auditing into our accessibility tests, we were able to pinpoint other accessibility barriers that automated tests could not catch.

One area we began manually testing was for keyboard accessibility. We manually tested some key user paths without a mouse or trackpad to make sure that users can navigate using a keyboard alone. This helped us discover many accessibility barriers.

For example, let’s say a sighted keyboard user was trying to look for interesting open source projects on They’re on the “Projects” page and have just finished looking through the first page of projects on, and they’re excited to dig deeper. However, they encounter several issues when trying to get to the next page of projects. As they tab through the last project card and go to the pagination area of the page, elements that should not receive focus, such as the empty spacer above the pagination area, do receive focus. Continuing to tab through the page, the keyboard focus does not follow logical order. The user goes from the previous button to the footer links instead of continuing through the pagination to pages 1 through 735. After tabbing through the entire footer, the user is finally able to get the focus to the link for the second page, however they can’t trigger it to actually get there. The action to get to the second page can only be executed using the mouse. To fix this, we added keyboard support so that the user can get to the second page using the spacebar or enter key.

Changes to make the site keyboard accessible are important as users with motor disabilities may not be able to use a mouse or a trackpad to interact with the site, and users who are blind may rely on a keyboard for navigation. Additionally, this feature has the potential to help anyone at some point, such as in situations where a user has a temporary limitation like a broken arm or a broken mouse.

Manual testing also helped us pinpoint accessibility barriers by prompting us to consider how the site uses color to convey information. Information shouldn’t be conveyed through color alone, as users who have color vision deficiencies may struggle to understand the content.

Code Red

The original site heavily relied on color on the “How to Inventory Code” page in the “Inventory Code Field Definitions” section, which explains the schema fields to help agencies create their JSON files and publish their code inventories. Optional schema fields were marked in red, and the site largely relied on the user’s ability to see the red color.

But if you’re colorblind, you might not be able to tell what text is red. These are two examples of simulations of what the section would look like if a user was red-colorblind or had monochromatic vision.

Simulations of what the “Inventory Code Field Definitions” section would look like for a user who is Red-Blind/Achromatopsia (left) or with Monochromacy/Protanopia (right)

To fix this, we added a second indicator to supplement the color change to make sure users can tell which fields are optional. By noting which fields are optional next to the field name, it not only helps those who have color vision deficiencies, but also it helps any user who may have missed the text that explained the meaning behind the red understand that these fields are optional. (As a side note, we made the optional fields blue instead of red since red makes it seem as if it’s especially important or a warning, which can cause confusion to the true purpose of the red text, which is that these fields are optional.)

The updated “Inventory Code Field Definitions” section includes the text “optional” next to optional fields so it no longer relies solely on the use of color to convey whether a field is optional.

Lessons Learned

As designers and developers, we have a responsibility to build with accessibility in mind. While we may not realize this, the way our code is structured and our color choices may be limiting who can participate and engage with these products and platforms. In building thoughtfully and inclusively, we have the power to create more enriching and meaningful experiences for everyone.

We’re always looking for ways to improve accessibility and welcome your ideas on how we can make better. Feel free to email us at



Sharing America’s Code