Web Performance SEO: Accessibility Contrast Error Fix
When to use
- PSI/Lighthouse accessibility shows "!" or error instead of a numeric score
- color-contrast audit errors or getImageData failures
- Need to improve accessibility signals that impact SEO
Workflow
- Reproduce
- Run Lighthouse or PSI; capture failing audit names.
- Scan code for common triggers
- CSS filters/backdrop blur, mix-blend-mode - OKLCH/OKLAB colors - Low opacity backgrounds (< 0.4) - Gradient text with color: transparent - Text over images without opaque overlays
- Fix in priority order
- Remove filters/blend modes - Convert OKLCH/OKLAB to HSL/RGB - Raise opacity thresholds - Add solid-color fallback for gradient text - Add overlay behind text on images
- Verify locally with Lighthouse/axe
- Verify in PSI after deployment
Fast scan commands
rg -n "backdrop-blur|filter:|mix-blend-mode" .
rg -n "oklch|oklab" .
rg -n "/10|/20|/30|opacity-25|opacity-0" .
rg -n "background-clip.*text|color.*transparent" .Fix patterns
Remove filters (critical)
// Before
<div className="bg-card/50 backdrop-blur-sm">...</div>
// After
<div className="bg-card/80">...</div>Convert OKLCH/OKLAB to HSL/RGB
/* Before */
:root { --primary: oklch(0.55 0.22 264); }
/* After */
:root { --primary: hsl(250, 60%, 50%); }Raise opacity thresholds
- Backgrounds >= 0.4 (prefer >= 0.6)
- Replace /10 -> /40, /20 -> /40, /30 -> /60
Gradient text fallback
.title { color: #111111; }
@media (prefers-contrast: no-preference) {
.title.with-gradient {
background: linear-gradient(90deg, #0ea5e9, #6366f1);
-webkit-background-clip: text;
background-clip: text;
color: transparent;
}
}
@media (forced-colors: active) {
.title.with-gradient { background: none; color: CanvasText; }
}Overlay for text on images
<div className="relative">
<img src="/hero.jpg" alt="Hero" />
<div className="absolute inset-0 bg-black/60"></div>
<h1 className="relative text-white">Title</h1>
</div>Acceptance criteria
- Accessibility score is numeric (not "!")
- color-contrast audit passes or lists actionable items
- Contrast ratios >= 4.5:1 for normal text, >= 3:1 for large text
Notes
- "!" indicates audit failure, not a low score.
- Always test locally before waiting for PSI updates.