All Access: Code.gov Website Front-End Updates Provide Greater Accessibility for America’s Code
By Anna Zhang, Code.gov 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 Code.gov 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 Code.gov 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. Code.gov 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 Code.gov 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 Code.gov, 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 Code.gov’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 Code.gov 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 Code.gov’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.
Navigation
We replaced the custom-developed main navigation menu of the Code.gov 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.
The Tools of the Trade
From buttons and dropdowns to the grid system and spacing units, we were able to use USWDS throughout the Code.gov 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, Code.gov 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 Code.gov 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 Code.gov. They’re on the “Projects” page and have just finished looking through the first page of projects on Code.gov, 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 Code.gov 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.
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.)
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 Code.gov better. Feel free to email us at code@gsa.gov.
