Back to Details

web-performance-seo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Web Performance SEO: Accessibility Contrast Error Fix

网页性能SEO：可访问性对比度错误修复

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
  • PSI/Lighthouse可访问性评分显示「!」或错误，而非数字分数
  • 出现color-contrast审核错误或getImageData失败
  • 需要提升影响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
  1. 复现问题
    • 运行Lighthouse或PSI；记录失败的审核项名称。
  2. 扫描代码排查常见触发因素
    • CSS滤镜/背景模糊（backdrop blur）、混合模式（mix-blend-mode）
    • OKLCH/OKLAB颜色格式
    • 低透明度背景（< 0.4）
    • 使用color: transparent的渐变文本
    • 无不透明遮罩的图片上方文本
  3. 按优先级修复
    • 移除滤镜/混合模式
    • 将OKLCH/OKLAB转换为HSL/RGB格式
    • 提高透明度阈值
    • 为渐变文本添加实色降级方案
    • 为图片上方的文本添加遮罩层
  4. 本地使用Lighthouse/axe验证
  5. 部署后在PSI中验证

Fast scan commands

快速扫描命令

bash
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" .
bash
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)

移除滤镜（关键修复）

tsx
// Before
<div className="bg-card/50 backdrop-blur-sm">...</div>
// After
<div className="bg-card/80">...</div>
tsx
// Before
<div className="bg-card/50 backdrop-blur-sm">...</div>
// After
<div className="bg-card/80">...</div>

Convert OKLCH/OKLAB to HSL/RGB

将OKLCH/OKLAB转换为HSL/RGB

css
/* Before */
:root { --primary: oklch(0.55 0.22 264); }
/* After */
:root { --primary: hsl(250, 60%, 50%); }
css
/* 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
  • 背景透明度≥0.4（推荐≥0.6）
  • 将/10替换为/40，/20替换为/40，/30替换为/60

Gradient text fallback

渐变文本降级方案

css
.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; }
}
css
.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

图片上方文本的遮罩层

tsx
<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>
tsx
<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
  • 可访问性评分为数字（而非「!」）
  • color-contrast审核通过或列出可操作的改进项
  • 普通文本对比度≥4.5:1，大文本对比度≥3:1

Notes

注意事项

  • "!" indicates audit failure, not a low score.
  • Always test locally before waiting for PSI updates.
  • 「!」表示审核失败，而非分数过低。
  • 等待PSI更新前，务必先在本地测试。