WCAG 2.1 AA requires a minimum contrast ratio of 4.5:1 for normal body text and 3:1 for large text (bold 18px+ or regular 24px+) and UI components like buttons and form borders. An inaccessible theme is the single most common source of WCAG failures on WordPress sites, and the good news is that block themes make this more fixable than classic themes did — your entire color system usually lives in one place, theme.json, instead of scattered across template files.
The Actual Numbers to Hit
| Element | Minimum contrast ratio (WCAG AA) |
|---|---|
| Normal body text | 4.5:1 |
| Large text (bold 18px+/regular 24px+) | 3:1 |
| UI components (buttons, input borders) | 3:1 |
| Focus indicators against adjacent color | 3:1 |
| Body text in dark mode (practitioner guidance, beyond minimum) | 15:1-17:1 recommended |
Where This Actually Lives in a Block Theme
Your theme’s color palette, defined once in theme.json, determines contrast site-wide far more than any individual page’s content. Check every text/background combination your palette actually produces in practice — not just the obvious body-text-on-white pairing, but button text on your accent color, muted secondary text (a common failure point, since “subtle” gray text is exactly where sites quietly fall under 4.5:1), and link colors against both light and dark section backgrounds if your site alternates them.
Common Failure Points
- Muted/secondary text colors — a lighter gray used for captions or metadata is the most common accidental AA failure.
- Text over gradient or image backgrounds — contrast has to hold up against the lightest part of the image or gradient, not just the average.
- Focus indicators — easy to forget entirely, but WCAG 1.4.11 requires a visible focus outline with 3:1 contrast against what’s next to it.
- Placeholder text in form fields — often styled lighter than real input text and quietly non-compliant as a result.
How to Check It
- Pull the actual hex values from your
theme.jsonpalette rather than guessing from how colors look on screen. - Run every real text/background pairing through a contrast checker (WebAIM’s is a common free option) — check pairs as they’re actually used, not just the two most obvious colors.
- Check focus states specifically, tabbing through the page rather than only checking static screenshots.
- Re-check after any palette change — a single color-scheme tweak can silently break contrast on components that were previously fine.
If you’re addressing accessibility for a dealer site specifically, we cover the broader ADA compliance picture in Car Dealer Website Accessibility: ADA Guide for 2026. If you want your theme’s color palette audited for contrast, get in touch.
Frequently Asked Questions
Does using a block theme automatically make my site accessible?
No — block themes make color and structure easier to fix since they’re centralized in theme.json, but the actual color choices and semantic markup still have to be correct. The theme is a better starting point, not a guarantee.
What’s the most common contrast failure on WordPress sites?
Muted or secondary text colors — the lighter grays commonly used for captions, dates, or metadata frequently fall under the 4.5:1 minimum without anyone noticing.
Do I need higher contrast for dark mode than light mode?
The WCAG minimum (4.5:1) technically applies either way, but many accessibility practitioners recommend aiming higher in dark mode specifically — often 15:1 to 17:1 for body text — since light text on dark backgrounds can still feel harder to read even when it technically passes.
Featured image: original illustration.