Color Contrast Guidelines

Color contrast is crucial for ensuring that text and interactive elements are readable by all users, including those with visual impairments. Proper contrast ratios help meet accessibility standards and improve the overall user experience.

Why Color Contrast Matters

Text that doesn’t have sufficient contrast against its background can be difficult or impossible to read for many users. Good contrast ensures that:

• Users with low vision can read text clearly
• Content is readable in various lighting conditions
• Users with color vision deficiencies can distinguish elements
• All users benefit from clear, readable content

WCAG Contrast Requirements

Level AA (Minimum)

• Normal text: 4.5:1 contrast ratio
• Large text: 3:1 contrast ratio (18pt or 14pt bold)

Level AAA (Enhanced)

• Normal text: 7:1 contrast ratio
• Large text: 4.5:1 contrast ratio

CSS Variables for Consistent Contrast

:root {
  /* High contrast colors for dark theme */
  --text-primary: #ffffff;
  --text-secondary: #e1e4e8;
  --text-muted: #b8b8b8;
  --bg-primary: #1a1a1a;
  --bg-secondary: #2d2d2d;
  --accent-primary: #007bff;
  --accent-secondary: #0056b3;
  --error-color: #d32f2f;
  --success-color: #2e7d32;
  --warning-color: #ed6c02;
}

[data-theme="light"] {
  /* High contrast colors for light theme */
  --text-primary: #000000;
  --text-secondary: #333333;
  --text-muted: #666666;
  --bg-primary: #ffffff;
  --bg-secondary: #f5f5f5;
  --accent-primary: #0056b3;
  --accent-secondary: #003d82;
  --error-color: #b71c1c;
  --success-color: #1b5e20;
  --warning-color: #e65100;
}

Text Contrast Examples

Good Contrast (AA Compliant)

/* Dark text on light background */
.text-good {
  color: #333333;
  background-color: #ffffff;
  /* Contrast ratio: 12.6:1 - Excellent */
}

/* Light text on dark background */
.text-good-dark {
  color: #ffffff;
  background-color: #1a1a1a;
  /* Contrast ratio: 15.6:1 - Excellent */
}

/* Blue text on white background */
.text-accent {
  color: #0056b3;
  background-color: #ffffff;
  /* Contrast ratio: 7:1 - AAA compliant */
}

Poor Contrast (Not Accessible)

/* Light gray text on white background */
.text-poor {
  color: #cccccc;
  background-color: #ffffff;
  /* Contrast ratio: 1.6:1 - Very poor */
}

/* Yellow text on white background */
.text-poor-yellow {
  color: #ffff00;
  background-color: #ffffff;
  /* Contrast ratio: 1.1:1 - Extremely poor */
}

/* Light blue text on light gray background */
.text-poor-blue {
  color: #87ceeb;
  background-color: #f0f0f0;
  /* Contrast ratio: 1.4:1 - Very poor */
}

Interactive Element Contrast

Buttons and Links

/* Good button contrast */
.btn-primary {
  background-color: #0056b3;
  color: #ffffff;
  /* Contrast ratio: 7:1 - AAA compliant */
}

.btn-primary:hover {
  background-color: #003d82;
  color: #ffffff;
  /* Contrast ratio: 11.2:1 - Excellent */
}

/* Good link contrast */
.link-good {
  color: #0056b3;
  text-decoration: underline;
  /* Contrast ratio: 7:1 against white background */
}

.link-good:hover {
  color: #003d82;
  text-decoration-thickness: 2px;
  /* Contrast ratio: 11.2:1 against white background */
}

Form Elements

/* Input field with good contrast */
.input-field {
  background-color: #ffffff;
  border: 2px solid #666666;
  color: #333333;
  /* Text contrast: 12.6:1 - Excellent */
  /* Border contrast: 4.5:1 - AA compliant */
}

.input-field:focus {
  border-color: #0056b3;
  outline: 2px solid #0056b3;
  outline-offset: 2px;
  /* Focus indicator contrast: 7:1 - AAA compliant */
}

/* Error state with good contrast */
.input-error {
  border-color: #d32f2f;
  background-color: #ffebee;
  color: #333333;
  /* Text contrast: 12.6:1 - Excellent */
  /* Border contrast: 4.5:1 - AA compliant */
}

Status and Feedback Colors

Success Messages

.success-message {
  background-color: #e8f5e8;
  border: 1px solid #2e7d32;
  color: #1b5e20;
  /* Text contrast: 7.5:1 - AAA compliant */
  /* Border contrast: 4.5:1 - AA compliant */
}

Error Messages

.error-message {
  background-color: #ffebee;
  border: 1px solid #d32f2f;
  color: #b71c1c;
  /* Text contrast: 7.5:1 - AAA compliant */
  /* Border contrast: 4.5:1 - AA compliant */
}

Warning Messages

.warning-message {
  background-color: #fff3e0;
  border: 1px solid #ed6c02;
  color: #e65100;
  /* Text contrast: 7.5:1 - AAA compliant */
  /* Border contrast: 4.5:1 - AA compliant */
}

Non-Text Contrast

Focus Indicators

/* Good focus indicator */
.focus-visible {
  outline: 2px solid #0056b3;
  outline-offset: 2px;
  /* Contrast ratio: 7:1 - AAA compliant */
}

/* Alternative focus indicator */
.focus-visible-alt {
  box-shadow: 0 0 0 2px #ffffff, 0 0 0 4px #0056b3;
  /* Inner white border, outer blue border */
  /* Blue contrast: 7:1 - AAA compliant */
}

Borders and Dividers

/* Good border contrast */
.border-good {
  border: 1px solid #666666;
  /* Contrast ratio: 4.5:1 - AA compliant */
}

/* Good divider contrast */
.divider {
  border-top: 1px solid #cccccc;
  /* Contrast ratio: 3:1 - AA compliant for large elements */
}

Common Contrast Mistakes

❌ Bad: Insufficient text contrast

.text-bad {
  color: #999999;
  background-color: #ffffff;
  /* Contrast ratio: 2.8:1 - Below AA requirement */
}

❌ Bad: Relying only on color

<!-- Bad: Using only color to indicate required fields -->
<input type="text" style="border-color: red;" />
<span style="color: red;">* Required</span>

❌ Bad: Low contrast focus indicators

.focus-bad {
  outline: 1px solid #cccccc;
  /* Contrast ratio: 1.6:1 - Very poor */
}

❌ Bad: Inconsistent contrast across themes

/* Dark theme with poor contrast */
[data-theme="dark"] .text-bad {
  color: #666666;
  background-color: #1a1a1a;
  /* Contrast ratio: 2.8:1 - Below AA requirement */
}

Testing Color Contrast

Manual Testing

1. Use contrast checkers: WebAIM, Color Contrast Analyzer
2. Test in different lighting: Bright sunlight, dim rooms
3. Test with color vision simulators: Chrome DevTools
4. User testing: Get feedback from users with visual impairments

Automated Testing

// Example: Check contrast ratios programmatically
function checkContrastRatio(color1, color2) {
  // Convert colors to luminance and calculate ratio
  const luminance1 = getLuminance(color1);
  const luminance2 = getLuminance(color2);
  
  const lighter = Math.max(luminance1, luminance2);
  const darker = Math.min(luminance1, luminance2);
  
  return (lighter + 0.05) / (darker + 0.05);
}

function getLuminance(color) {
  // Convert hex to RGB and calculate luminance
  const rgb = hexToRgb(color);
  const [r, g, b] = [rgb.r, rgb.g, rgb.b].map(c => {
    c = c / 255;
    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}

Advanced Contrast Patterns

High Contrast Mode Support

@media (prefers-contrast: high) {
  :root {
    --text-primary: #000000;
    --text-secondary: #000000;
    --bg-primary: #ffffff;
    --accent-primary: #000000;
    --border-color: #000000;
  }
  
  [data-theme="dark"] {
    --text-primary: #ffffff;
    --text-secondary: #ffffff;
    --bg-primary: #000000;
    --accent-primary: #ffffff;
    --border-color: #ffffff;
  }
}

Reduced Motion Support

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

Focus Indicators for High Contrast

/* High contrast focus indicators */
@media (prefers-contrast: high) {
  .focus-visible {
    outline: 3px solid;
    outline-offset: 2px;
  }
  
  button:focus,
  input:focus,
  select:focus,
  textarea:focus {
    outline: 3px solid;
    outline-offset: 2px;
  }
}

Remember: Good color contrast is essential for accessibility and usability. Always test your color combinations with contrast checkers and consider the needs of users with visual impairments.