Every WordPress accessibility engagement produces decisions. Why a particular color combination was chosen. How a complicated form was made keyboard-navigable. Which third-party embed was vetted, which was rejected. Almost none of these decisions get written down, and a year later nobody remembers them. Here's what to capture, when, and what future-you (or your successor) will need to find it.
Accessibility work on a WordPress site is an ongoing process, not a one-time push. Plugins update, content changes, new components get added, third-party scripts come and go. Each one creates a small accessibility decision — should this color combo pass; how should this form field be labeled; does this new embed introduce a barrier. The decisions are real engineering work. They’re also, in almost every project I’ve audited, completely undocumented — which means the next person who touches the site re-decides them from scratch, sometimes wrong.
What undocumented accessibility looks like.
Six months after a fresh accessibility pass, a typical site looks like this:
- The CTA button color was changed; nobody knew the original passed contrast at 4.5:1 with the brand background, and the new color doesn’t
- A new form field was added with a placeholder instead of a label, because the developer didn’t know that placeholders aren’t a substitute for labels
- A third-party calendar embed was installed without checking its accessibility, because there was no record of which embeds had been previously vetted
- The accordion component on a new page uses different ARIA than the accordion on the original audit, because nobody documented which pattern was chosen and why
Each of these is a small regression. Each could have been prevented by 30 seconds of writing during the original decision. The cost of finding and fixing them later is dramatically higher than the cost of writing them down in the first place.
What to actually capture.
You don’t need a 50-page accessibility manifesto. You need a living document with five sections:
- Approved color combinations. Background color + text color + the contrast ratio at the size and weight it’s used at. Anything that passes WCAG 2.2 AA goes on the list. The design system can reference this list; new colors get added only after they’re checked. This single document prevents most of the contrast regressions that hit redesigns.
- Approved patterns for common components. The accessible accordion pattern you chose (and why). The accessible modal pattern. The accessible navigation pattern. The accessible form-error pattern. Each one written as “here’s the HTML/ARIA we use, here’s why, here’s what to avoid.” A developer adding a new component checks this list first.
- Decisions that were intentional but might look wrong. “The header logo is an
imgnot an SVG because the SVG version caused issues with screen reader announcements. Don’t change it without testing.” The most expensive kind of accessibility regression is the one introduced by a developer trying to “fix” something that was intentional. - Third-party integrations vetted (and rejected). “Calendly: accessible, approved. AcuityScheduling: failed keyboard nav, rejected. Cal.com: approved after configuration X. YouTube embeds: approved for accessibility but rejected on privacy; use locally-hosted alternative.” A new request to add an embed gets checked against this list first.
- Open issues and trade-offs. “Form CAPTCHA currently uses reCAPTCHA v2 image challenges, which are inaccessible. Investigated alternatives; hCaptcha has same problem; current mitigation is allowing audio CAPTCHA fallback. Ticket logged to migrate to an invisible alternative like Cloudflare Turnstile or reCAPTCHA v3 in Q3.” Surfaces what’s known-broken so it doesn’t get forgotten.
Where it lives.
The format matters less than that the document is somewhere a developer will actually find it. A few options that consistently work:
- A markdown file in the theme repository (
docs/accessibility.md). Lives with the code, visible in code review, version-controlled. My default for projects with engineering ownership. - A page in the team wiki. Useful when non-developers also need to read it (designers, content team, project managers). Less likely to be updated as code changes.
- An options page in the WordPress admin. If the editor team needs to reference accessibility decisions (e.g., approved color combinations for content blocks), having them in the WP admin makes them visible at the point of use.
The wrong location is “a Google Doc the designer made during the original engagement.” That document will be lost within a year.
What this prevents in practice.
The compound effect over a couple years on a maintained site:
- Color contrast regressions caught at design review instead of after launch
- New components built using the same patterns as old ones — consistent experience for assistive technology users
- Third-party integrations evaluated against a known bar instead of rediscovered each time
- The next developer onboarding finds the “here’s how we do accessibility” document instead of guessing
- The next audit cycle finds fewer net-new findings, because the patterns are already understood
Documentation is the cheapest accessibility tool in the toolkit. It doesn’t catch bugs — it prevents them from being introduced. The 30 minutes spent writing the decision down at the time of the decision is, in compound terms, one of the highest-return things you can do in an accessibility engagement. See accessibility that holds up for the rest of how the practice fits together.