color-contrast-auditor

颜色对比度审计器

检测导致文本难以阅读的颜色对比度违规，并提供符合 WCAG 的修复方案。结合数学对比度分析和通过视觉能力进行的感知评估。

适用场景

适用于：

• 怀疑存在对比度问题的网站或应用截图
• 用于颜色审计的 CSS/Tailwind 文件
• “我看不清这个”或“这个很难看清”
• 发布前的无障碍检查
• 设计系统颜色验证

不适用于：

• 选择品牌颜色（使用 web-design-expert）
• 色彩和谐度／美学（使用 color-theory-palette-harmony-expert）
• 非视觉无障碍（屏幕阅读器、键盘导航）

---

WCAG 2.1 对比度要求

最低比例（AA — 必需）

文本类型	最低比例	示例
普通文本（<24px，<18.66px 粗体）	4.5:1	正文、标签、按钮
大号文本（≥24px 或 ≥18.66px 粗体）	3:1	标题、主视觉文本
UI 组件（边框、图标）	3:1	表单输入框、图标、焦点环
图形对象	3:1	图表、信息图

增强比例（AAA — 推荐）

文本类型	最低比例
普通文本	7:1
大号文本	4.5:1

非文本元素

元素	要求
焦点指示器	与相邻颜色的对比度为 3:1
表单字段边框	与背景的对比度为 3:1
传达含义的图标	与背景的对比度为 3:1
禁用元素	无要求（但请考虑用户体验）

---

对比度公式

Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)

Where L1 = lighter color's relative luminance
      L2 = darker color's relative luminance

计算相对亮度

function relativeLuminance(r, g, b) {
  // Convert 0-255 to 0-1
  let [rs, gs, bs] = [r, g, b].map(c => c / 255);

  // Apply gamma correction
  const gamma = c => c <= 0.03928
    ? c / 12.92
    : Math.pow((c + 0.055) / 1.055, 2.4);

  const [R, G, B] = [rs, gs, bs].map(gamma);

  // Weighted sum (human eye sensitivity)
  return 0.2126 * R + 0.7152 * G + 0.0722 * B;
}

function contrastRatio(color1, color2) {
  const l1 = relativeLuminance(...color1);
  const l2 = relativeLuminance(...color2);
  const lighter = Math.max(l1, l2);
  const darker = Math.min(l1, l2);
  return (lighter + 0.05) / (darker + 0.05);
}

---

常见的不合格模式

1. 浅色文本配浅色背景

❌ FAILING EXAMPLE (from user screenshot):

┌─────────────────────────────────────────────┐
│  Background: #F5F2E8 (beige/cream)          │
│  Text: #C8FF00 (lime green)                 │
│                                             │
│     "Scan. Crawl. Match. Report."           │
│     ← UNREADABLE                            │
│                                             │
│  Calculated Ratio: ~1.5:1                   │
│  Required: 4.5:1 (normal) or 3:1 (large)    │
│  Verdict: FAIL by 3x                        │
└─────────────────────────────────────────────┘

✅ FIXED OPTIONS:
   • Darken text to #5A7300 → Ratio: 4.5:1
   • Darken background to #2A2A2A → Ratio: 12:1
   • Use dark green #1A4D00 → Ratio: 8:1

2. 灰色文本综合征

❌ COMMON FAILURE:
   Background: #FFFFFF
   Text: #AAAAAA (light gray)
   Ratio: 2.3:1 ← FAIL

✅ FIXES:
   • Text: #767676 → Ratio: 4.5:1 (minimum AA)
   • Text: #595959 → Ratio: 7:1 (AAA)

3. 看起来明亮的高饱和度颜色

❌ DECEPTIVE FAILURE:
   Background: #FFF8E7 (warm white)
   Text: #FF6B6B (coral/salmon)
   Ratio: 2.8:1 ← FAIL (looks "colorful" but fails)

✅ FIXES:
   • Text: #C62828 (darker red) → Ratio: 5.2:1
   • Text: #8B0000 (dark red) → Ratio: 8.1:1

4. 流行的低对比度美学风格

❌ "MINIMALIST" FAILURE:
   Background: #FAFAFA
   Text: #E0E0E0
   Ratio: 1.3:1 ← SEVERELY FAILING

This is NOT minimalism. This is inaccessible.

✅ MINIMALIST + ACCESSIBLE:
   Background: #FAFAFA
   Text: #616161 → Ratio: 5.7:1

5. 占位符文本颜色太浅

❌ COMMON FORM FAILURE:
   Input background: #FFFFFF
   Placeholder: #CCCCCC
   Ratio: 1.6:1 ← FAIL

✅ FIX:
   Placeholder: #757575 → Ratio: 4.6:1

6. 渐变背景

❌ VARIABLE CONTRAST:
   Gradient: #FFFFFF → #000080
   Text: #FFFFFF (fixed)

   Top of gradient: 1:1 (invisible!)
   Bottom of gradient: 8.6:1 (good)

✅ SOLUTIONS:
   • Add text shadow/outline
   • Use semi-transparent overlay behind text
   • Ensure ALL gradient stops pass contrast

---

审计方法

第 1 步：目视扫描（截图分析）

收到截图时，识别以下内容：

1. 按字号分类的文本元素：

   • 标题（大号文本 → 要求 3:1）
   • 正文（普通文本 → 要求 4.5:1）
   • UI 标签（按钮、链接 → 4.5:1）
   • 说明文字／小字（要求 4.5:1）

2. 交互元素：

   • 按钮边框／背景
   • 表单字段边框
   • 焦点状态
   • 具有含义的图标

3. 需要留意的问题：

   • 浅色文本配浅色背景
   • 灰色文本配白色背景
   • 彩色文本配彩色背景
   • 图片上的文本没有叠加层

第 2 步：提取颜色

从 CSS／代码中：

# Find all color declarations
grep -E "(color:|background:|#[0-9a-fA-F]{3,8}|rgb|hsl)" styles.css

从 Tailwind 中：

# Find text/bg color classes
grep -E "(text-|bg-)" *.tsx *.jsx

第 3 步：计算比例

对于每一组文本／背景颜色：

1. 将颜色转换为 RGB
2. 计算相对亮度
3. 计算对比度
4. 与 WCAG 要求进行比较

第 4 步：生成报告

# Contrast Audit Report

## Summary
- Total color pairs tested: X
- Passing (AA): Y
- Failing: Z
- Critical failures (<2:1): N

## Failures by Severity

### Critical (Ratio < 2:1)
| Location | Foreground | Background | Ratio | Required | Fix |
|----------|------------|------------|-------|----------|-----|
| Hero tagline | #C8FF00 | #F5F2E8 | 1.5:1 | 3:1 | #5A7300 |

### Moderate (Ratio 2:1 - 3:1)
...

### Minor (Ratio 3:1 - 4.5:1, normal text only)
...

## Recommended Fixes
[Specific color replacements with new ratios]

---

色盲注意事项

对比度要求有所帮助，但无法完全解决色盲问题。还需进行以下检查：

需要考虑的类型

类型	受影响人群	注意事项
绿色盲	6% 的男性	难以区分红色和绿色
红色盲	2% 的男性	红色看起来较暗
蓝黄色盲	<1%	难以区分蓝色和黄色

最佳实践

1. 切勿只依赖颜色来传达含义

   • 添加图标、图案或文本标签
   • 使用红色／绿色表示错误／成功时，也需要配合图标

2. 测试容易混淆的颜色组合：

   • 红色 + 绿色（停止／通行）
   • 蓝色 + 紫色
   • 绿色 + 棕色
   • 浅绿色 + 黄色

3. 确保亮度差异足够

   • 即使色相相同，不同的亮度也有帮助

---

速查：安全的颜色组合

在白色背景上（#FFFFFF）

用例	颜色	十六进制	比率
正文	深灰色	#333333	12.6:1
次要文本	中灰色	#767676	4.5:1
链接	蓝色	#0066CC	5.3:1
成功	绿色	#2E7D32	5.1:1
错误	红色	#C62828	6.0:1
警告	橙棕色	#E65100	4.5:1

在黑色背景上（#000000）

用例	颜色	十六进制	比率
正文	浅灰色	#E0E0E0	13.4:1
次要文本	中灰色	#9E9E9E	6.3:1
强调色	浅蓝色	#90CAF9	7.3:1

在深灰色背景上（#1A1A1A）

用例	颜色	十六进制	比率
正文	米白色	#F5F5F5	14.1:1
次要文本	浅灰色	#BDBDBD	8.3:1

---

工具与验证

在线检查工具

• WebAIM 对比度检查器
• Coolors 对比度检查器
• Adobe Color 无障碍功能

浏览器开发者工具

// Chrome DevTools: Elements → Styles → hover color swatch
// Shows contrast ratio automatically

// Firefox: Accessibility Inspector
// Shows color contrast issues

自动化测试

// axe-core (popular a11y testing library)
const axe = require('axe-core');
axe.run(document, { rules: ['color-contrast'] });

// Lighthouse (built into Chrome)
// Performance → Accessibility → Color contrast

命令行工具

# Lighthouse CLI
npx lighthouse https://example.com --only-categories=accessibility

# Pa11y
npx pa11y https://example.com

---

与此技能的集成

分析截图或代码库时：

1. 我会识别所有文本与背景的颜色组合
2. 我会计算每种组合的对比度
3. 我会标记任何低于 WCAG AA 阈值的组合
4. 我会建议符合要求的具体十六进制颜色值
5. 我会提供前后对比

对于示例截图（米色背景上的青柠色）：

AUDIT RESULT: CRITICAL FAILURE

Element: Hero tagline "Scan. Crawl. Match. Report."
Foreground: ~#C8FF00 (lime green)
Background: ~#F5F2E8 (beige)
Calculated Ratio: ~1.5:1
Required (large text): 3:1
Required (normal text): 4.5:1
Status: ❌ FAILS BY 2-3x

RECOMMENDED FIXES:
1. Darken text to #5A7300 (olive) → 4.8:1 ✓
2. Darken text to #3D5C00 (dark olive) → 7.1:1 ✓✓
3. Keep lime, darken BG to #3D3D3D → 8.2:1 ✓✓
4. Use #1B5E20 (dark green) → 8.4:1 ✓✓

---

新设计检查清单

发布前：

• 所有正文的对比度均不低于 4.5:1
• 所有大号文本的对比度均不低于 3:1
• 所有表单边框的对比度均不低于 3:1
• 所有传达含义的图标的对比度均不低于 3:1
• 占位符文本清晰可读（≥4.5:1）
• 焦点状态清晰可见（≥3:1）
• 链接不单靠颜色也能区分
• 错误/成功状态使用图标，而不只是颜色
• 已使用色盲模拟器进行测试
• 自动化无障碍扫描通过

---

**理念：**美观的设计与无障碍并非互不相容。高对比度可以醒目、鲜明且经过精心设计。低对比度不是“极简主义”，而是排斥用户。每个难以辨认的词都会让一位用户流失。