Accessible Color Contrast in Web Themes

Beautiful themes are useless if people can't read the text. Color contrast is the most common accessibility issue in web design - and one of the easiest to fix when you address it from the start.

This guide covers WCAG 2.2 contrast requirements and how to apply them to Nuxt UI themes.

WCAG Contrast Requirements

The Web Content Accessibility Guidelines (WCAG) 2.2 define minimum contrast ratios:

Text Contrast (Level AA)

Text Type	Minimum Ratio	Examples
Normal text (< 24px)	4.5:1	Body copy, labels, descriptions
Large text (≥ 24px or ≥ 18.5px bold)	3:1	Headings, hero text
Incidental text	No requirement	Disabled buttons, decorative text

Non-Text Contrast (Level AA)

Element	Minimum Ratio	Examples
UI components	3:1	Button borders, input outlines, toggles
Graphical objects	3:1	Icons, chart elements, focus indicators
State indicators	3:1	Active tabs, selected items, checked states

Common Contrast Pitfalls in Theming

1. Light Text on Light Backgrounds

The most frequent issue. gray-400 text on a white background fails contrast:

❌ gray-400 on white = ~2.5:1 (fails 4.5:1)
✅ gray-600 on white = ~5.8:1 (passes)

For secondary/muted text, use shade 600 or darker on light backgrounds.

2. Colored Text on Colored Backgrounds

Using your primary color for both text and backgrounds creates contrast problems:

❌ indigo-500 text on indigo-50 bg = ~3.2:1 (fails for small text)
✅ indigo-700 text on indigo-50 bg = ~6.1:1 (passes)

3. Dark Mode Contrast Failures

Bright text on very dark backgrounds can technically pass contrast ratios but still cause readability issues due to excessive contrast causing halation:

⚠️  white (#fff) on black (#000) = 21:1 (passes but causes eye strain)
✅ gray-100 text on gray-950 bg = ~16:1 (high contrast, less strain)

4. Button and Input Borders

UI component boundaries must have 3:1 contrast against adjacent colors:

❌ gray-200 border on white bg = ~1.3:1 (invisible)
✅ gray-400 border on white bg = ~2.5:1 (still fails!)
✅ gray-500 border on white bg = ~3.7:1 (passes)

Checking Contrast in Nuxt UI Themes

In the Theme Builder

The Theme Builder previews your theme across 125+ real components. When evaluating contrast:

Check body text - paragraphs, labels, and descriptions should be clearly legible
Check muted text - timestamps, help text, and secondary content
Check buttons - text on solid buttons, border visibility on outline buttons
Check inputs - placeholder text, border visibility, focus rings
Check both modes - light and dark mode independently