mcpField
W
web-performance-seo

web-performance-seo

github.com/mavcuiDesign & UI19388 installsUpdated 33w ago
Repository

About web-performance-seo

A skill for diagnosing and fixing web accessibility contrast issues that cause Lighthouse or PSI audits to fail. It guides code scanning, prioritized CSS changes, and local and post-deployment verification.

Key features

  1. 01Identify common CSS contrast audit triggers
  2. 02Scan code for filters, color formats, and opacity issues
  3. 03Apply prioritized contrast and fallback fixes
  4. 04Verify with Lighthouse or axe locally and PSI after deployment

Use cases

  1. 01Investigate a Lighthouse or PSI accessibility audit showing an error
  2. 02Resolve color-contrast or getImageData audit failures
  3. 03Check contrast improvements before and after deployment

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/mavcui/agent-skills-hunter --skill web-performance-seo

After installing, type/web-performance-seoin Claude Code to confirm it loaded.

Details

From the project README

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

  1. Reproduce
    • Run Lighthouse or PSI; capture failing audit names.
  2. 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
  3. 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
  4. Verify locally with Lighthouse/axe
  5. 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.

Comments

Markdown supported