Hitting WCAG AA contrast on every VeloCMS theme
How to verify and fix colour-contrast issues across the 30 shipped themes (and any custom one you build), with the exact tools and tolerances WCAG actually defines.
Contrast is the single accessibility check that catches the most readers — and the easiest one to ignore until someone complains. WCAG 2.1 Level AA requires 4.5:1 for body text and 3:1 for large text or non-text UI. That's not a suggestion. Below that and 30% of readers under cataract-onset age start struggling; below 3:1 and most users on a sunny patio screen can't read the page at all.
Run the audit in 30 seconds
Open your blog in Chrome → DevTools → Lighthouse → check "Accessibility" → Generate report. The report flags every failing contrast pair with the actual ratio and target. Lighthouse uses the official WCAG algorithm, so the numbers are accurate.
For deeper diagnosis use axe DevTools (https://www.deque.com/axe/devtools/). It surfaces the exact CSS selector for each failure, which makes the fix one-line.
The usual suspects on a blog
Across the 30 themes shipped with VeloCMS, four categories cause 90% of failures:
- Meta text — author byline + date — using --muted on --bg. Often hovers around 3.5:1, just below the 4.5:1 body-text threshold.
- Link colour against the page background — old themes ship with a brand blue that looks fine on white but loses contrast on light grey card surfaces.
- Disabled button states — most design systems mute buttons to 40% opacity, which drops contrast below 3:1.
- Placeholder text in input fields — the default placeholder colour in many themes is too light.
Fixes that don't ruin the design
You don't need to abandon a light pastel palette to hit AA. Three moves close most gaps:
- Darken --muted by ~15% — open the Custom Theme tab and bump the lightness component of the OKLCH value down. The text feels the same; the ratio jumps.
- Add a font-weight bump for small text — 14px body at weight 500 reads more legibly at the same contrast than 14px at weight 400. WCAG counts "bold + 14px" as large text (3:1 minimum).
- Underline links — adding text-decoration: underline gives readers a non-colour cue, so the contrast ratio can fall to 3:1 (large-text threshold) without failing AA.
When you really need a low-contrast accent
Brand colours sometimes demand low-contrast pastels — fashion, beauty, photography niches especially. Reserve those for decorative surfaces (background washes, borders, icons inside oversized cards). Keep body copy and primary CTAs on a high-contrast pair. Visitors with low vision use OS-level accessibility shortcuts (high-contrast mode, dark mode) that already swap your palette — make sure your theme respects @media (prefers-contrast: more) by bumping the relevant variables.