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
無効化された要素	要件なし（ただし UX を考慮してください）

---

コントラスト比の計算式

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）上

用途	色	Hex	比率
本文	ダークグレー	#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）上

用途	色	Hex	比率
本文	ライトグレー	#E0E0E0	13.4:1
補助	ミディアムグレー	#9E9E9E	6.3:1
アクセント	ライトブルー	#90CAF9	7.3:1

ダークグレー（#1A1A1A）上

用途	色	Hex	比率
本文	オフホワイト	#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

CLI ツール

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

# Pa11y
npx pa11y https://example.com

---

このスキルとの統合

スクリーンショットまたはコードベースを分析する際：

1. 特定します：すべてのテキストと背景色の組み合わせ
2. 計算します：それぞれのコントラスト比
3. 警告します：WCAG AA の基準を下回るもの
4. 提案します：基準を満たす具体的な Hex 値
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以上）
• 色だけに頼らずリンクを見分けられる
• エラー／成功状態を色だけでなくアイコンでも示す
• 色覚シミュレーターでテスト済み
• 自動アクセシビリティスキャンに合格

---

理念： 美しいデザインとアクセシビリティは両立します。高いコントラストは印象的で、ドラマチックで、意図的なデザインにできます。低いコントラストは「ミニマリスト」ではなく、排他的です。読めない言葉が一つあるたびに、ユーザーを一人失います。