Accessible Design System v1

Understanding Opacity and Contrast Testing

Not all uses of rgba() or opacity are problematic for accessibility. This section explains when opacity is acceptable and when it creates accessibility issues that require manual testing.

Rule of Thumb

Can accessibility tools test the contrast automatically?

• YES: Use solid colors with CSS variables → Tools can verify compliance
• NO: Avoid opacity, or be prepared to manually test → Tools cannot verify compliance

When Opacity IS Acceptable

These decorative effects don't affect text contrast and don't need contrast testing:

/* ✓ ACCEPTABLE: Shadows are decorative, not tested for contrast */
:root {
    --ds-ads-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1);
    --ds-ads-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
}

.card {
    box-shadow: var(--ds-ads-shadow-md);
    /* Shadow creates depth, no text on shadow itself */
}

When Opacity REQUIRES Manual Testing

These scenarios prevent automated contrast testing and require manual verification:

/* ⚠ REQUIRES MANUAL TESTING */
.overlay {
    background-image: url('hero.jpg');
    position: relative;
}

.overlay::before {
    content: "";
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    background-color: rgba(0, 0, 0, 0.6); /* Semi-transparent overlay */
}

.overlay-content {
    position: relative;
    z-index: 1;
    color: white; /* Text on overlay */
}

/* You must manually test this with your actual image:
   1. Take screenshot in Photoshop/Figma
   2. Use eyedropper to get actual text color
   3. Use eyedropper to get actual background (overlay + image)
   4. Check contrast ratio manually
*/

/* ⚠ REQUIRES MANUAL TESTING */
.gradient-background {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
}

/* Test contrast at BOTH ends of gradient:
   1. Test white text against #667eea (lightest point)
   2. Test white text against #764ba2 (darkest point)
   3. Use whichever is LOWER as your contrast ratio
   4. If lowest point fails 4.5:1, adjust gradient colors
*/

/* ❌ WRONG: Opacity prevents automated testing */
.button-wrong:hover {
    background-color: rgba(0, 102, 204, 0.1);
    /* Tools cannot verify text contrast */
}

/* ✓ RIGHT: Solid color enables automated testing */
:root {
    --ds-ads-primary-bg-lightest: #fafcfe; /* Solid hex color */
}

.button-right:hover {
    background-color: var(--ds-ads-primary-bg-lightest);
    /* Tools verify: 16.8:1 contrast ratio ✓ */
}

How to Manually Test Opacity Scenarios

When you must use opacity or scenarios that prevent automated testing:

1. Screenshot Method (Most Accurate):
   • Take a full-resolution screenshot of your design
   • Open in Photoshop, Figma, or similar tool
   • Use eyedropper to sample the actual rendered text color
   • Use eyedropper to sample the actual rendered background color
   • Enter both colors into WebAIM Contrast Checker
   • Verify minimum 4.5:1 ratio for normal text (3:1 for large text)
2. Browser DevTools Method:
   • Right-click the text element
   • Inspect → Computed tab
   • Look for "color" value (rendered color after opacity)
   • Look for "background-color" value (rendered color)
   • Test these values in contrast checker
3. Test Multiple Scenarios:
   • For gradients: Test at lightest AND darkest points
   • For images: Test with multiple representative images
   • For overlays: Test worst-case scenario (lightest image)

Summary: When to Use What

Key Takeaway

Default to solid colors with CSS variables for all text and interactive elements. This enables automated contrast testing and ensures WCAG compliance. Only use opacity when absolutely necessary for the design, and commit to manual testing with real content.