Collaborating with engineers to ensure web accessibility.

Problem Statement

How might we ensure all users have an equitable experience across our website and web app?

Audit

Principal's Digital Accessibility Policy took effect in May of 2025 and it was announced in June or July of 2024, so we had about a year to prepare. The policy stated that any new development starting in May would have to meet A and AA WCAG 2.2 standards. However, until the policy took effect, web accessibility was never prioritized. Hoping to make it easier to meet accessibility requirements, the engineers figured out away to import PDS components which had built-in accessibility considerations. While automated testing with tools like Lighthouse in Chrome DevTools gave us scores for accessibility in the 80s and web best practices scores in the 40s and 50s, manual testing using a keyboard with VoiceOver uncovered a host of problems.

Enter Figma's Annotation Tool

In April of 2025, just before the new policy went into effect, we were adding a new feature into our web app. Knowing the implementation would take us until the end of April and beginning of May before release, I knew we would have to address any accessibility concerns. This is when Figma introduced their annotation tool, which I took advantage of to help make recommendations to make the pages more accessible.

It turned out to be a very helpful tool to communicate suggestions and expectations with the engineers.

Predicting Opportunities

I surveyed our front-end engineers and none of them had experience with building accessible experiences. I knew I had by work cut out for me, but I wanted to be as helpful as I could so I took it upon myself to learn as much as I could about web best practices and implementing accessibility techniques. I began annotating everything in Figma, knowing the penchant for using divs for everything.

• Heading levels.
• Ordered lists, unordered lists, and list items.
• WAI-ARIA properties.
• Alt text for images.
• Descriptive page titles.

A preview of the types of annotations I would leave for the engineers.

While I've had some past experience with accessibility, testing keyboard navigation, and screen reader experience, I have always relied on engineers to know how to make it work. This was a real learning experience for me diving deep into front-end HTML and making a page functionally accessible.

I spent a ton of time researching best practices, keyboard functionality, ARIA roles and properties, and how to meet success criteria for A and AA conformance levels. I annotated my way through the Figma designs based on my understanding of my research, but I couldn't say with high confidence that my suggestions would help without testing them, so I made sure to always refer to my suggestions as "recommendations" and never "requirements."

Collaboration With Engineers

During the handoff of the design files, I showed the engineers the new annotation tool and how to read the recommendations. I encouraged them to do their own research, I linked to documentation, articles, and tutorials I used to make the suggestions, and told them to challenge me if they found better ways to make things accessible.

During the development process, I was in constant contact with the engineers, answering questions in chat, hopping on calls, and providing recommendations if they ran into hurdles or if I learned something new. For example, when one of our new pages required a form with an input field, I uncovered the fact that the inputs we had been using throughout the site were not accessible, they didn't have an accessible name. I gave my analysis on the problem and suggestions on how to fix the issue.

Testing in Lower Environments

As the engineers were working on these improvements, they would publish their changes to a testing environment where I could validate them.

• The end-to-end flow for the feature was navigable by keyboard.
• Navigating the page with a screen reader, I used Apple VoiceOver, made sense and followed the logical flow of the page.
• Using automated testing tools like SiteImprove and Lighthouse in Chrome DevTools didn't uncover any major issues.

If I found issues during my testing, I would communicate them with the engineer and we made the call if they were blocking issues or if the fix could wait.

Progress Over Perfection

Since the team and I were new to developing an accessible product, there was a lot of back-and-forth communication to get the new feature in a good state. Testing the new pages in lower environments uncovered a dozen changes that required attention, but only a couple really impacted the user experience for screen reader users.

However, this journey to accessibility was not going to happen over night, so we made the call to ship the feature to production while I created tasks in Jira to track the fixes needed. These were quickly addressed in the next release.

Accessibility issues found during testing and recorded as tasks in Jira.

When I could, I provided as much information as I could to explain what the issue was and what a potential fix could be, including some example code.

Details of one of the tasks created in Jira with example code of how to fix the issue.

The biggest issue we faced was the tech stack that Elevate was built on and our implementation of the PDS components. Because the PDS components weren't built for Salesforce Experience Cloud, our engineers had to work their magic to import them into Salesforce for us to use. This resulted in each individual PDS component being wrapped within a Salesforce component, which gave us a lot of heartache. It made it extremely difficult for the engineers to make simple changes like the example code above.

There was good news just around the corner, however. The engineers had been exploring options for migrating to a new tech stack and rebuilding the product outside of Salesforce.

Migrating Tech Stacks

There was an enterprise-level initiative at our parent company to develop web applications using a Next.js meta-framework, Next Software Kit (NSK), that our engineers adopted. This gave us the opportunity to directly adopt and inject PDS components, giving us a deeper level of control and making accessibility changes so much easier.

Result: Allows us to directly inject PDS components to leverage the built-in accessibility considerations. It also gives us a lot more control over the rest of the elements on the page and the ability to add any attributes, roles, and properties needed to make the page more accessible.

Production Ready

• An accessible experience in our product.
• The ability to leverage PDS components and their built-in accessibility.
• More lightweight code with improved load speed.
• Passing scores in testing tools like Lighthouse and Siteimprove.

We'll continue to make improvements as we migrate the remaining pages. I'm currently auditing our existing features and adding accessibility recommendations for when we are ready to migrate them. I feel more confident now in my recommendations and the abilities of our front-end engineers after the first NSK page rebuild. After the first page and the changes we made before and after shipping to production, I have a solid grasp of the kinds of recommendations would make the biggest impact. I will continue to work with the engineers and evolve these annotations as we progress.

Recommendations for making one of the cards on the dashboard more accessible.

The one exception, so far, is our mobile navigation menu that opens in a modal. Rob Dodson has called modals, "the boss battle at the end of web accessibility," and I have to agree. I know this will be difficult to get right just based on the research I've done. I'll provide updates as we tackle this menu and maybe create a case study specifically for it if it turns out to be super difficult.

Recommendations for making our mobile menu accessible.

Lessons Learned

• A good foundation is key, migrating our tech stack from Salesforce Experience Cloud to NSK has made the world of difference.
• Creating an accessible web experience can get complicated, but knowing the technical side will help inform my future designs. For example, I will think twice about using modals.

I feel much more confident now in my understanding of what it takes to meet WCAG A and AA conformance level, but I'm still learning more every day.

Next Steps

• Continue migrating our product from Salesforce to NSK.
• Designing and developing our experience with accessibility in mind.
• Leverage our connection with Principal's User Experience team to find and recruit disabled users to test with.
• Continue learning more about web accessibility and I aim to earn my IAAP certification.

With these plans, we strive to deliver an equitable experience for all of our users.