Bringing a long-established documentation site to WCAG 2.2 AA

Context

A health tech company had commissioned an external vendor to run a representative accessibility audit of its web application. Because it’s healthcare, the compliance requirements were critical.

I joined after the audit, to bring the company’s legacy documentation site up to WCAG 2.2 AA.

The challenge

The documentation site was a long-established MadCap Flare project. Flare is the help-authoring tool the documentation was written and published in, and moving away from it wasn’t an option. That was a fixed constraint: every fix had to work within it. The site had more than 100 accessibility issues, and they weren’t all the same kind of problem:

• Colour contrast couldn’t be fixed by simply darkening colours. The site had to stay on brand.
• Interactive components failed in ways an automated scan only partly sees: focus traps, missing accessible names, keyboard navigation that didn’t work, and state changes that assistive technology never heard about.
• Flare’s output often couldn’t be made semantically accessible at all, however the content was authored.
• Fixing it once wasn’t enough. Without a way to catch new issues, the site would drift back out of conformance.

What I did

1. Planned the remediation with the Director and Head Manager of Documentation and the Director of UX.
2. Started with colour contrast, working with the Director of UX on an AA-conformant palette that stayed on brand.
3. Fixed component-level issues: focus management, accessible names and ARIA, keyboard navigation, and announcing state changes.
4. Built a post-build pipeline that patched Flare’s output into accessible HTML before deploy, with automated tests confirming every patch ran.
5. Had the result validated by an expert accessibility tester: WCAG 2.2 AA conformance, with more than 100 issues resolved.
6. Put prevention in place: automated axe-core checks in GitHub Actions, my own Playwright accessibility tests for complex interaction states, and training opportunities for the writing team.

Colour first, because it took the longest

Accessible colour that still looks like the brand takes design judgement, not just a contrast checker. It took several rounds with the Director of UX to land a palette that met AA and that the design side was happy with. Starting with colour gave those cycles the time they needed.

Component-level fixes

Most of the remaining issues lived in interactive components:

• Focus traps, where keyboard users could get stuck or lose their place
• Missing accessible labels and ARIA attributes, so controls had no name for screen reader users
• Keyboard navigation that didn’t reach or operate every control
• State changes, such as opening, closing or expanding, that weren’t communicated to assistive technology

The image lightbox is a good example of working within the constraint. Flare couldn’t be replaced, but its built-in lightbox was completely inaccessible, so swapping out that one component was the best call. I replaced it with the open-source GLightbox library and modified GLightbox to make it accessible, without changing the rest of the Flare project.

Patching what Flare couldn’t produce

Some problems couldn’t be fixed inside Flare at all, because its templates and output often didn’t allow semantically accessible HTML.

So I built a post-build pipeline: after Flare generated the site, a set of patches rewrote the output into accessible HTML before it was deployed. Patching generated output is a workaround, and its risk is a patch silently failing if Flare’s output changes. To close that gap, I added automated tests that confirm every patch ran before a deploy can go out.

Keeping it accessible

A one-off fix decays. To stop that, I added two layers of automated testing that run on every change:

• axe-core in GitHub Actions, to catch common, detectable issues before they ship
• A suite of my own Playwright accessibility tests for the things a static scan can’t see: complex interaction states, focus movement, and regressions in the components I’d fixed

I also identified training for the writing team, so the people creating content know how to keep it accessible. It covered the things authors control directly:

• Heading structure: headings in a logical order that reflects the content, not chosen for their size
• Accessible tables and lists: proper header cells for data tables, and real list markup instead of manually typed bullets or numbers
• Alt text: describing what an image shows and why it matters, and marking purely decorative images so screen readers skip them
• Accessible link names: link text that makes sense on its own, instead of “click here” or “learn more”

Impact

• The documentation site reached WCAG 2.2 AA conformance, validated by an expert accessibility tester.
• More than 100 accessibility issues were resolved, including ones Flare couldn’t fix on its own, through a tested post-build patch pipeline.
• Automated checks in GitHub Actions now guard against regressions on every change.
• The writing team has a clear training plan for building accessibility into how they write: heading structure, tables and lists, alt text, and link names.

What I’d do differently

Treat constraints as part of the design, from day one. Flare wasn’t going anywhere, and the work went best when I designed fixes around it: replacing one inaccessible component, and patching its output after the build when it couldn’t produce accessible HTML itself. Naming the constraints at the start makes it easier to see where a targeted swap beats a workaround.

Build the infrastructure and the community as you go, not at the end. The GitHub Actions checks and the writing team’s training are what keep the site accessible after I’ve gone. Setting them up alongside the remediation, rather than after it, means every fix is protected from the moment it lands, and the people who own the content are part of keeping it accessible.