Zach Willis

508 Refactor

Championing Accessibility

It all started with a podcast. I was rolling into the office listening to Full Stack Radio and Adam Watham had Ryan Florence on talking about his new project, Reach UI. And then the shame set in. I had been riding high off my big CSS/Sass conversion effort and knew this had to be an issue for our app. That night I got home, installed a screen reader and hung my head like Johnny Cash.

This Is Embarrassing

508 seems to be one of those things we all know we should be doing but for some reason it’s not a priority and like maintaining good alignment in design mockups, when time is an issue, it falls off the radar. This was not a problem I was looking forward to solving but I have a remedy for such moments of weakness. I’ve found that developing a healthy level of hatred for a business problem you’re trying to solve is a very effective motivator. So I taped some cardboard over my sunglasses, popped in my headphones and tried to use our app. I really hate being blind and using our app. Now there’s lots of different variations of human-computer-interaction that can be negatively affected by poor design and 508 implementation, but this taste of being blind was enough to fuel my fire for the issue.

What Do You Mean It’s Not An Issue

So getting buy-in was actually difficult when it came to pitching this as the UI team’s latest passion project. I thought it would be a slam dunk because it had built in value-add. I had taken a random sampling of W3C validation results (valid HTML is just one layer of compliance) and proven that by taking this on, not only would we be compliant and accessible, but our HTML was in worse shape than I realized so we would be performing good maintenance too. The leads didn’t seem impressed and deprioritized the effort which I barely kept alive through shear insistence. Luckily, we had just expanded our user base to cover a new customer who truly values 508 compliance and when the lead business analysis emphasized this at an all hands briefing, my support strengthened.

How Does One Simply 508

I hate to admit it, but I was lacking a good appreciation for what goes into making something 508 compliant. I would spend my free time reading the spec and then diving into the Google rabbit hole to figure out how to solve the problem. I spent about 2 months’ worth of down time just reading.

Establishing A Workflow

With knowledge in my head and a healthy list of references bookmarked I set about outlining an ideal workflow that we could apply, page by page, to eventually bring the whole app up to spec.

  1. Run the page against the W3C HTML Validator and fix any and all errors and warnings. Cool, now we have clean HTML.
  2. Run a 508 analysis rule against the page. We use the aXe Chrome extension. Fix it all up again but this time we’re touching HTML and CSS.
  3. Review the view file for HTML5 semantics. We decided since no one on our team is an ARIA expert and since bad ARIA is worse than no ARIA we would stick with HTML5.
  4. Retest the page and make sure you didn’t introduce new problems.
  5. Now we should have a pretty solid page. Time to validate against the HHS 508 Checklist!
  6. Verify with the UI team that whatever changes you made align with our standards and discuss lessons you learned performing the refactor.
  7. Open a Pull Request.
  8. Rinse and repeat 270 times.


This is still an ongoing project for us but I’m really happy with how the workflow is helping everyone on the team get a lot stronger with considering HTML not just in terms of the refactor, but how we markup new features we’re rolling out. For myself, one of the strongest images that sticks with me and fuels my passion for 508 was reading about users with dexterity issues who navigate websites by having to bump their head against a pad. It helps me to consider just how uniquely people interact with the things we create as designers and programmers and that we have an obligation to everyone to make the internet a place that is truly open and accessible.

Check out my other case studies here.