Color Contrast | Blue Frog Docs

Color Contrast

Diagnose and fix insufficient color contrast to ensure text readability for all users

Color Contrast

What This Means

Color contrast measures the difference in brightness between text (or other important visual elements) and its background. Insufficient contrast makes content difficult or impossible to read, particularly for users with low vision, color blindness, or anyone viewing in bright sunlight or on poor-quality displays.

WCAG Contrast Requirements

Normal Text (< 24px or < 18px bold):

  • Level AA: 4.5:1 minimum contrast ratio
  • Level AAA: 7:1 minimum contrast ratio

Large Text (≥ 24px or ≥ 18px bold):

  • Level AA: 3:1 minimum contrast ratio
  • Level AAA: 4.5:1 minimum contrast ratio

UI Components & Graphics:

  • Level AA: 3:1 minimum contrast ratio
  • Required for icons, form inputs, focus indicators

Impact on Your Business

Legal Compliance:

  • Color contrast is required under WCAG 2.1 Level AA
  • One of the most frequently cited accessibility violations
  • Can result in lawsuits and legal liability
  • Essential for ADA and Section 508 compliance

User Experience:

  • Affects 8% of men and 0.5% of women (color blindness)
  • Affects users with low vision (millions globally)
  • Benefits all users in bright environments
  • Improves readability on all devices

Business Impact:

  • Poor contrast reduces conversion rates
  • Users can't read calls-to-action
  • Increases bounce rates
  • Damages brand perception

Additional Benefits:

  • Improves readability in sunlight
  • Better experience on low-quality displays
  • Helps users with reading difficulties
  • Creates clearer visual hierarchy

How to Diagnose

  1. Open your website in Chrome
  2. Right-click text → "Inspect"
  3. In Elements panel, look for contrast information
  4. Chrome shows contrast ratio and compliance:
    • ✓ Green checkmark = passes
    • ⚠️ Warning = fails AA or AAA
  5. Click the color swatch to open color picker
  6. Adjust color to see suggested accessible alternatives

What to Look For:

  • Contrast ratio number (e.g., "3.2:1")
  • AA and AAA compliance indicators
  • Suggested colors that meet requirements
  • Element font size and weight

Method 2: WAVE Browser Extension

  1. Install WAVE Extension
  2. Navigate to your webpage
  3. Click WAVE icon
  4. Click "Contrast" tab
  5. Review contrast errors and alerts

What to Look For:

  • Red "Very low contrast" errors (fails AA)
  • Yellow "Low contrast" alerts (fails AAA)
  • Number of affected text elements
  • Specific color combinations failing

Method 3: axe DevTools

  1. Install axe DevTools Extension
  2. Open Chrome DevTools (F12)
  3. Navigate to "axe DevTools" tab
  4. Click "Scan ALL of my page"
  5. Look for "Color contrast" violations
  6. Review "Serious" and "Moderate" issues

What to Look For:

  • Contrast ratio for each violation
  • Expected vs actual ratios
  • Specific elements affected
  • Color values (foreground/background)

Method 4: Lighthouse Accessibility Audit

  1. Open Chrome DevTools (F12)
  2. Navigate to "Lighthouse" tab
  3. Select "Accessibility" category
  4. Click "Generate report"
  5. Look for "Background and foreground colors have a sufficient contrast ratio"

What to Look For:

  • Failed audit items
  • Number of elements affected
  • Specific elements to fix
  • Impact on accessibility score

Method 5: Online Contrast Checkers

WebAIM Contrast Checker:

  1. Visit WebAIM Contrast Checker
  2. Enter foreground color (text)
  3. Enter background color
  4. Review results:
    • Contrast ratio
    • AA/AAA compliance for normal/large text
    • Suggested color adjustments

Colorable:

  1. Visit Colorable
  2. Test color combinations
  3. View contrast matrix
  4. Generate accessible color palettes

General Fixes

Fix 1: Darken Text or Lighten Background

Adjust colors to meet 4.5:1 ratio:

  1. Dark text on light background:

    /* Failing - 3.2:1 */
.text {
  color: #767676; /* Light gray */
  background: #ffffff; /* White */
}

/* Passing - 4.6:1 */
.text {
  color: #595959; /* Darker gray */
  background: #ffffff; /* White */
}

  2. Light text on dark background:

    /* Failing - 2.8:1 */
.text {
  color: #cccccc; /* Light gray */
  background: #333333; /* Dark gray */
}

/* Passing - 4.9:1 */
.text {
  color: #f0f0f0; /* Lighter gray */
  background: #333333; /* Dark gray */
}

  3. Use contrast checker to find exact values:

    • Enter current colors
    • Adjust until ratio ≥ 4.5:1
    • Update CSS with new values

Fix 2: Fix Colored Text

Common issue: colored text on white:

  1. Links:

    /* Failing - 2.9:1 */
a {
  color: #0099ff; /* Light blue */
}

/* Passing - 4.5:1 */
a {
  color: #0066cc; /* Darker blue */
}

  2. Buttons:

    /* Failing - 3.1:1 */
.button {
  color: #28a745; /* Green */
  background: #ffffff;
}

/* Passing - 4.5:1 */
.button {
  color: #ffffff; /* White text */
  background: #28a745; /* Green background */
}

  3. Status indicators:

    /* Failing */
.warning { color: #ffcc00; } /* Yellow - 1.8:1 */

/* Passing */
.warning {
  color: #ffffff; /* White text */
  background: #d39e00; /* Darker yellow background */
  padding: 0.25em 0.5em;
  border-radius: 4px;
}

Fix 3: Fix Overlay Text

Text over images or gradients:

  1. Add background overlay:

    .hero {
  position: relative;
  background-image: url('hero.jpg');
}

.hero::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: rgba(0, 0, 0, 0.5); /* Dark overlay */
}

.hero-text {
  position: relative;
  color: #ffffff;
  z-index: 1;
}

  2. Add text shadow for contrast:

    .text-over-image {
  color: #ffffff;
  text-shadow:
    1px 1px 2px rgba(0, 0, 0, 0.8),
    -1px -1px 2px rgba(0, 0, 0, 0.8),
    1px -1px 2px rgba(0, 0, 0, 0.8),
    -1px 1px 2px rgba(0, 0, 0, 0.8);
}

  3. Use solid background box:

    .text-box {
  background: rgba(0, 0, 0, 0.8);
  color: #ffffff;
  padding: 1em;
}

Fix 4: Fix Placeholder Text

Form placeholders must have sufficient contrast:

  1. Default placeholder contrast:

    /* Failing - usually around 2:1 */
input::placeholder {
  color: #999999;
}

/* Passing - 4.5:1 */
input::placeholder {
  color: #757575;
}

  2. Or use labels instead of placeholders:

    <!-- Better approach -->
<label for="email">Email address</label>
<input id="email" type="email">

Fix 5: Fix Button and Form Contrast

Interactive elements need 3:1 contrast:

  1. Button contrast:

    /* Check button text contrast */
.button {
  color: #ffffff;
  background: #007bff;
  /* Contrast: 4.5:1 ✓ */
}

/* Check button border contrast with background */
.button-outline {
  color: #007bff;
  background: #ffffff;
  border: 2px solid #007bff;
  /* Border contrast: 8.6:1 ✓ */
}

  2. Form input borders:

    /* Failing - 2.5:1 */
input {
  border: 1px solid #cccccc;
  background: #ffffff;
}

/* Passing - 3:1 */
input {
  border: 1px solid #767676;
  background: #ffffff;
}

  3. Focus indicators:

    /* Ensure visible focus with sufficient contrast */
button:focus,
input:focus {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
  /* Contrast: 8.6:1 ✓ */
}

Fix 6: Don't Rely on Color Alone

Provide additional visual indicators:

  1. Error states:

    <!-- Bad - color only -->
<input class="error" type="text">

<!-- Good - color + icon + text -->
<div class="field-error">
  <input type="text" aria-invalid="true" aria-describedby="error-msg">
  <span class="error-icon">⚠</span>
  <p id="error-msg" class="error-text">Invalid email format</p>
</div>

  2. Required fields:

    <!-- Bad - red asterisk only -->
<label>Name <span style="color: red;">*</span></label>

<!-- Good - asterisk + text + required attribute -->
<label>
  Name <span class="required" aria-label="required">*</span>
</label>
<input type="text" required>
<p class="help-text">Required field</p>

  3. Links in text:

    /* Don't rely on color only */
a {
  color: #0066cc;
  text-decoration: underline; /* Visual indicator */
}

/* Or add on hover */
a:hover,
a:focus {
  text-decoration: underline;
  font-weight: bold;
}

Fix 7: Create Accessible Color System

Build contrast into design system:

  1. Define color variables with guaranteed contrast:

    :root {
  /* Backgrounds */
  --bg-primary: #ffffff;
  --bg-secondary: #f8f9fa;
  --bg-dark: #212529;

  /* Text on light backgrounds */
  --text-primary: #212529;      /* 16.1:1 on white */
  --text-secondary: #6c757d;    /* 4.6:1 on white */

  /* Text on dark backgrounds */
  --text-light-primary: #ffffff;   /* 16.1:1 on dark */
  --text-light-secondary: #adb5bd; /* 6.7:1 on dark */

  /* Interactive */
  --color-link: #0066cc;        /* 7.7:1 on white */
  --color-button: #007bff;      /* 4.5:1 with white text */
}

  2. Use semantic color classes:

    <div class="bg-light text-dark">
  <!-- Always paired for sufficient contrast -->
</div>

<div class="bg-dark text-light">
  <!-- Always paired for sufficient contrast -->
</div>

  3. Document color combinations:

    /* Safe combinations - pre-tested for contrast */
.combo-1 { color: #212529; background: #ffffff; } /* 16.1:1 */
.combo-2 { color: #ffffff; background: #007bff; } /* 4.5:1 */
.combo-3 { color: #000000; background: #ffc107; } /* 10.4:1 */

Platform-Specific Guides

Detailed implementation instructions for your specific platform:

Platform Troubleshooting Guide
Shopify Shopify Color Contrast Guide
WordPress WordPress Color Contrast Guide
Wix Wix Color Contrast Guide
Squarespace Squarespace Color Contrast Guide
Webflow Webflow Color Contrast Guide

Verification

After fixing contrast issues:

  1. Re-run automated tests:

    • WAVE extension (no red contrast errors)
    • axe DevTools (no contrast violations)
    • Lighthouse (passes color contrast audit)

  2. Use Chrome DevTools:

    • Inspect text elements
    • Verify contrast ratios ≥ 4.5:1
    • Check AA and AAA indicators

  3. Test with color blindness simulators:

    • Chrome DevTools > Rendering > "Emulate vision deficiencies"
    • Test: Protanopia, Deuteranopia, Tritanopia
    • Verify content still readable

  4. Real-world testing:

    • View site in bright sunlight (mobile device)
    • Test on low-quality monitor
    • Verify readability in various conditions

  5. Manual review:

    • Check all text content
    • Verify buttons and form elements
    • Test hover and focus states
    • Confirm error messages visible

Common Mistakes

  1. Light gray text on white - Very common, often fails
  2. Colored links without underlines - Color alone insufficient
  3. Yellow/light colors on white - Almost never sufficient contrast
  4. Thin fonts at small sizes - Requires higher contrast
  5. Text over complex background images - No consistent contrast
  6. Placeholders as labels - Usually insufficient contrast
  7. Focus indicators too subtle - Must have 3:1 contrast
  8. Disabled state too light - Should still be readable
  9. Assuming current monitor represents all users - Test objectively
  10. Fixing only obvious violations - Check all text systematically

Color Contrast Quick Reference

Common Contrast Ratios

Grays on White (#ffffff):

  • #000000 - 21:1 (maximum contrast)
  • #212529 - 16.1:1 (AAA large, AAA normal)
  • #495057 - 9.4:1 (AAA large, AAA normal)
  • #6c757d - 4.6:1 (AA large, AA normal)
  • #adb5bd - 2.4:1 (fails all)
  • #dee2e6 - 1.5:1 (fails all)

Common Brand Colors on White:

  • Blue #0066cc - 7.7:1 (AAA large, AAA normal)
  • Blue #007bff - 4.5:1 (AA large, AA normal)
  • Green #28a745 - 3.1:1 (AA large only)
  • Red #dc3545 - 4.0:1 (AA large only)
  • Orange #fd7e14 - 2.3:1 (fails all)
  • Yellow #ffc107 - 1.4:1 (fails all)

Additional Resources

↑ Back to top
// SYS.FOOTER