Focus indicators that fail WCAG 1.4.11: real cases and exact fixes

ops> = ({ label, isFocused, onSelect, }) => { const handleKeyDown = (e: React.KeyboardEvent) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onSelect(); } };

// Dynamic style application based on state const optionStyle: React.CSSProperties = { backgroundColor: isFocused ? designTokens.interactiveFocusBg : designTokens.bgSurface, color: designTokens.textPrimary, border: 1px solid ${designTokens.interactiveBorderStrong}, padding: '0.5rem 0.75rem', cursor: 'pointer', outline: 'none', // Custom indicator handles visibility };

return ( <div role="option" aria-selected={isFocused} tabIndex={0} style={optionStyle} onKeyDown={handleKeyDown} onClick={onSelect} className={styles.optionTransition} > {label} </div> ); };

**Rationale for Choices:**
*   **Inline Styles for Tokens:** Using a `designTokens` object ensures that the exact hex values required for compliance are centralized. If an audit requires a change, updating the token object fixes all instances.
*   **State-Driven Background:** The `backgroundColor` switches explicitly based on `isFocused`. This guarantees that the focused state uses `#939393`, which is verified to meet 3:1.
*   **Explicit Border Definition:** The border uses `interactiveBorderStrong` (`#8094A3`). This addresses the common pitfall where borders are too light. Even if the design calls for a subtle border, the token enforces the minimum contrast.
*   **Keyboard Support:** The component includes `onKeyDown` handling. WCAG 1.4.11 is about perceivability, but perceivable components must also be operable. This example bundles operability for a complete solution.

### Pitfall Guide

| Pitfall Name | Explanation | Fix |
| :--- | :--- | :--- |
| **The Grey Scale Trap** | Using light greys (e.g., `#F0F0F0`) for backgrounds or borders to maintain a "clean" look. These often yield ratios below 2:1. | Replace light greys with darker neutral tones that hit 3:1. Use `#939393` or darker for interactive backgrounds. |
| **Border Blindness** | Assuming borders don't need contrast checks because they are "lines." WCAG 1.4.11 applies to all non-text UI components. | Audit all borders on inputs, cards, and dividers. Ensure border colors meet 3:1 against the adjacent background. |
| **Hover/Focus Desync** | Applying a high-contrast color to `:focus` but leaving `:hover` with a failing color. Users may perceive the element differently via mouse vs. keyboard. | Ensure `:hover` and `:focus` states share the same contrast-compliant color values. |
| **Adjacent Color Assumption** | Checking contrast against black or white, but the component sits on a colored background (e.g., a grey card). | Always measure contrast against the *actual* adjacent background color. A color passing on white may fail on `#F5F5F5`. |
| **Transparent Overlay Fallacy** | Using `rgba(0,0,0,0.1)` for focus states. Semi-transparent overlays can produce unpredictable contrast results depending on the underlying color. | Use solid color tokens for states. If transparency is required, calculate the blended result and verify the final ratio. |
| **Component Boundary Omission** | Designing input fields with no visible boundary (e.g., relying on placeholder text to indicate an input). | Add a visible border or background change that meets 3:1. The boundary must be perceivable even without text. |
| **Tooling Complacency** | Relying solely on automated scanners. Many scanners do not evaluate pseudo-classes like `:hover` or dynamic states. | Combine automated scans with manual keyboard navigation testing and manual contrast checks for all states. |

### Production Bundle

#### Action Checklist

- [ ] **Audit Design Tokens:** Review all color tokens used for borders, backgrounds, and focus states. Flag any greys lighter than `#939393` for verification.
- [ ] **Verify Ratios:** Use a contrast checker to measure all flagged tokens against their adjacent backgrounds. Ensure minimum 3:1.
- [ ] **Update Token Definitions:** Replace failing hex values with compliant colors (e.g., swap `#F1F4F4` for `#939393` in focus tokens).
- [ ] **Implement Token Architecture:** Refactor components to use design tokens instead of hardcoded colors. Ensure tokens are applied to all interactive states.
- [ ] **Manual Keyboard Test:** Navigate the application using only `Tab` and `Enter`. Verify that every interactive element has a clearly visible focus indicator.
- [ ] **Check Boundaries:** Inspect all input fields, radio buttons, and checkboxes. Confirm borders are visible and meet contrast requirements.
- [ ] **Regression Testing:** Add visual regression tests or snapshot tests that include focus states to prevent future contrast regressions.

#### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Global Design System Update** | Update Design Tokens | Fixes all components simultaneously. Prevents future violations. | Low (One-time token update) |
| **Legacy Component with Hardcoded Colors** | Refactor to Tokens | Hardcoded values cannot be managed centrally. Refactoring enables scalability. | Medium (Refactoring effort) |
| **Brand Color Fails 3:1** | Use Brand Color with Darker Variant | Brand colors often fail contrast. Create a "contrast-safe" variant for interactive states. | Low (Add variant token) |
| **Complex Backgrounds** | Dynamic Contrast Calculation | If backgrounds vary, static tokens may fail. Use CSS variables or JS to adjust contrast based on context. | High (Complex implementation) |
| **Focus Ring vs. Background Change** | Use Both or Background Change | Background changes provide larger visual area. Focus rings can be thin and fail if not thick/dark enough. | Low (CSS adjustment) |

#### Configuration Template

Use this CSS variable template to enforce 1.4.11 compliance across your project. These values are calibrated for white backgrounds. Adjust if your surface colors differ.

```css
:root {
  /* WCAG 1.4.11 Compliant Colors (Ratio >= 3:1 against #FFFFFF) */
  
  /* Interactive States */
  --color-interactive-focus-bg: #939393; /* Ratio 3.0:1 */
  --color-interactive-hover-bg: #939393; /* Ratio 3.0:1 */
  --color-interactive-selected-bg: #8094A3; /* Ratio 3.14:1 */
  
  /* Component Boundaries */
  --color-border-strong: #8094A3; /* Ratio 3.14:1 */
  --color-border-default: #949494; /* Ratio 3.03:1 */
  --color-border-input: #8094A3; /* Ratio 3.14:1 */
  
  /* Focus Indicators */
  --color-focus-ring: #0056D6; /* High contrast blue for outlines */
  --focus-ring-width: 2px;
  --focus-ring-offset: 2px;
}

/* Utility class for focus management */
.focus-visible-ring:focus-visible {
  outline: var(--focus-ring-width) solid var(--color-focus-ring);
  outline-offset: var(--focus-ring-offset);
}

Quick Start Guide

1. Install Contrast Tooling: Add a browser extension like "WCAG Contrast Checker" or "Stark" to your development environment.
2. Run Initial Audit: Open your application and use the tool to scan all interactive elements. Note any ratios below 3:1.
3. Apply Token Fixes: Update your CSS variables or design tokens with the corrected hex values from the template above.
4. Verify Compliance: Re-scan the application. Confirm all borders, focus states, and hover states now report ratios of 3:1 or higher.
5. Document Standards: Add a note to your design system documentation specifying that all non-text UI elements must maintain a minimum 3:1 contrast ratio. Include the approved color tokens.