Color Contrast and Readable Text
Use Tailwind's color shades to meet WCAG AA and AAA contrast ratios, and audit your palette for accessible text-on-background combinations.
Color Contrast and Readable Text is a free Tailwind CSS Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Tailwind CSS Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Color Contrast Matters
Color contrast is the visual difference between foreground text and its background. Low contrast makes text difficult to read — especially for users with low vision, color blindness, or those reading in bright sunlight. WCAG (Web Content Accessibility Guidelines) defines minimum contrast ratios that all web content should meet to be considered accessible to users with visual impairments. Meeting these ratios is both an ethical obligation and often a legal requirement.
WCAG Contrast Ratios Explained
WCAG defines two success criteria for contrast. AA (Level 2) requires a minimum ratio of 4.5:1 for normal text and 3:1 for large text (18pt+ or 14pt+ bold). AAA (Level 3) requires 7:1 for normal text and 4.5:1 for large text. The contrast ratio is calculated from the relative luminance of the two colors — white on black is 21:1 (maximum), while light gray on white can be less than 1.5:1 (fails).
/*
WCAG Contrast Ratio Requirements
Level AA (minimum standard):
- Normal text (< 18pt regular, < 14pt bold): 4.5:1
- Large text (≥ 18pt regular, ≥ 14pt bold): 3:1
- UI components (borders, icons): 3:1
Level AAA (enhanced standard):
- Normal text: 7:1
- Large text: 4.5:1
Common examples:
- black (#000) on white (#fff): 21:1 ✓ AAA
- gray-900 on white: ~18:1 ✓ AAA
- gray-600 on white: ~5.9:1 ✓ AA
- gray-400 on white: ~3.5:1 ✗ Fails AA
- white on blue-500: ~3.8:1 ✗ Fails AA for small text
*/Tailwind's Color Palette and Contrast
Tailwind's color palette is designed with a shade system from 50 to 950. The darker shades (700-900) on white backgrounds and the lighter shades (50-200) on dark backgrounds generally meet AA contrast requirements for body text. However, the mid-range shades (400-600) on white are a common accessibility pitfall — they often look acceptable visually but fail the 4.5:1 ratio required for normal-sized text.
<!--
Safe combinations for AA compliance on white:
text-gray-700 → 6.9:1 ✓
text-gray-800 → 10.5:1 ✓
text-gray-900 → 18.1:1 ✓
text-blue-700 → 5.5:1 ✓
text-blue-800 → 8.0:1 ✓
Risky on white (check before using):
text-blue-500 → 3.0:1 ✗ fails for normal text
text-gray-500 → 4.1:1 ✗ barely fails
text-gray-400 → 3.5:1 ✗ fails
Safe for large text (3:1 minimum):
text-blue-500 → 3.0:1 borderline for large text
-->
<p class="text-gray-700">Safe body text (6.9:1)</p>
<p class="text-gray-500">Check this! (4.1:1, barely fails)</p>Checking Contrast Ratios
Never rely on visual judgment alone for contrast ratios. Use dedicated tools: the WebAIM Contrast Checker (webaim.org/resources/contrastchecker/) for quick checks, browser DevTools which show the contrast ratio in the accessibility section of the inspector, and axe DevTools or Lighthouse for automated audits that scan the entire page. The goal is to audit every text/background combination, not just obvious ones.
/*
Tools for checking contrast:
1. Chrome DevTools:
- Select element
- Go to Computed > Color
- Click the color swatch → contrast ratio shown
2. WebAIM Contrast Checker:
- webaim.org/resources/contrastchecker/
- Enter foreground + background hex
- Shows AA and AAA pass/fail
3. Axe DevTools browser extension:
- Runs automated contrast checks on entire page
- Lists all violations with exact ratios
4. Storybook a11y addon:
- checks every component story automatically
*/Building a Contrast-Safe Color System
Design your Tailwind color palette so that semantic token pairs always meet the minimum contrast ratio. Pair your primary action color (e.g., blue-600 as background) with white text and verify the ratio. Define your secondary text color (e.g., gray-600) against your base surface (white) and verify. Document these approved pairs in your style guide so developers never need to guess whether a combination is safe.
/*
Contrast-safe token pairs (verified AA+)
==========================================
On white (#fff) surface:
text-text-primary = gray-900 → 18.1:1
text-text-secondary = gray-700 → 6.9:1
text-text-muted = gray-600 → 4.6:1 ✓ (just passes)
bg-action-primary = blue-600 (white text: 5.1:1 ✓)
bg-action-danger = red-600 (white text: 4.8:1 ✓)
On gray-900 (#111827) surface:
text = white or gray-100 → very high contrast
text-muted = gray-300 → 7.2:1 ✓
Check each pair at: webaim.org/resources/contrastchecker/
*/Text Size and Contrast
WCAG's lower contrast threshold for large text (3:1 vs 4.5:1) reflects the fact that larger text is easier to read at lower contrast. A color combination that fails for 14px body text may pass for an 18px heading or a 16px bold button label. Use Tailwind's text-lg (18px), text-xl, or larger for cases where a slightly lower-contrast color is necessary for design reasons — but always verify it still meets 3:1.
<!-- blue-500 on white: 3.0:1 — borderline for large text -->
<!-- FAILS: small body text at blue-500 on white -->
<p class="text-blue-500 text-sm">This is hard to read (3.0:1 fails AA)</p>
<!-- PASSES: large heading at blue-500 on white -->
<h1 class="text-blue-500 text-3xl font-bold">
Heading (3.0:1 passes for large text)
</h1>
<!-- BETTER: blue-700 meets AA for all text sizes -->
<p class="text-blue-700 text-sm">Safe body text (5.5:1)</p>Non-Text Contrast
WCAG also requires a 3:1 contrast ratio for non-text UI components — icons, form input borders, chart lines, and focus indicators. A gray-300 border on a white input field fails this requirement. Use gray-400 at minimum for borders on white backgrounds. Icon colors that are purely decorative are exempt, but icons that convey meaning (like a warning icon) must meet the 3:1 threshold.
<!-- Input border contrast check -->
<!-- FAILS: border-gray-300 on white = ~2.5:1 (fails 3:1 for UI) -->
<input class="border border-gray-300 rounded px-3 py-2" />
<!-- PASSES: border-gray-400 on white = ~3.5:1 -->
<input class="border border-gray-400 rounded px-3 py-2" />
<!-- PASSES: icon in context -->
<button class="flex items-center gap-2">
<!-- Meaningful icon: must meet 3:1 contrast -->
<SearchIcon class="h-5 w-5 text-gray-700" />
Search
</button>Accessible Link Colors
Links require dual distinctiveness: they must have sufficient contrast against the background (4.5:1) AND be visually distinguishable from surrounding non-link text. The default browser blue and underline style provides both. If you remove the underline (common in navigation), links must still be distinguishable by color alone — which requires a higher contrast differential between link and body text colors. Always keep underline on inline body text links.
<!-- Good: underline + adequate contrast -->
<p class="text-gray-800">
Learn more about
<a href='/docs' class="text-blue-700 underline hover:text-blue-900">
Tailwind CSS
</a>
in the official docs.
</p>
<!-- Acceptable in nav: no underline, but distinctly colored -->
<nav>
<a href='/about' class="text-blue-700 hover:text-blue-900 font-medium">
About
</a>
</nav>
<!-- Risky: remove underline from inline body text links -->
<!-- Visitors who are colorblind may not see link -->Color as the Only Differentiator
WCAG requires that information is never conveyed by color alone. A red error message identified only by its red color fails users who are color blind. Pair color with a text label, icon, or pattern. A green/red traffic-light status indicator needs an icon or text label. Tailwind makes it easy to add supplementary cues — use icons, ARIA labels, borders, or text alongside color to communicate meaning.
<!-- BAD: color is the only difference -->
<div class="bg-red-100">Something went wrong.</div>
<div class="bg-green-100">Success!</div>
<!-- GOOD: color + icon + label -->
<div class="bg-red-50 border border-red-200 flex items-center gap-2 p-3 rounded-lg">
<ExclamationTriangleIcon class="h-5 w-5 text-red-600 flex-shrink-0" />
<span class="text-red-800 text-sm font-medium">Error: Something went wrong.</span>
</div>
<div class="bg-green-50 border border-green-200 flex items-center gap-2 p-3 rounded-lg">
<CheckCircleIcon class="h-5 w-5 text-green-600 flex-shrink-0" />
<span class="text-green-800 text-sm font-medium">Success! Changes saved.</span>
</div>Dark Mode and Contrast
Dark mode introduces a new set of contrast challenges. Dark backgrounds require lighter text, and the same shades that worked on white do not work on dark surfaces. Build a parallel set of contrast-verified text colors for dark mode. In Tailwind, verify your dark:text-* classes meet the same WCAG thresholds as your light mode text — do not assume that lighter shades on dark backgrounds are automatically accessible.
<!-- Verify dark mode contrast too -->
<div class="bg-white dark:bg-gray-900">
<!-- Light mode: gray-800 on white = 12.6:1 ✓ -->
<!-- Dark mode: gray-200 on gray-900 = 11.4:1 ✓ -->
<h2 class="text-gray-800 dark:text-gray-200 text-xl font-semibold">
Heading
</h2>
<!-- Light mode: gray-600 on white = 4.6:1 ✓ -->
<!-- Dark mode: gray-400 on gray-900 = 5.9:1 ✓ -->
<p class="text-gray-600 dark:text-gray-400 text-sm">
Secondary text
</p>
</div>Automated Contrast Auditing
Integrate contrast checking into your development workflow with automated tools. axe-core as a Jest or Vitest plugin can fail your test suite on contrast violations. Storybook's a11y addon runs axe on every component story. Playwright with axe-playwright can run contrast audits on full pages in CI. Catching contrast failures automatically before review prevents regressions from reaching production.
// playwright accessibility audit in CI
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test('homepage has no contrast violations', async ({ page }) => {
await page.goto('http://localhost:3000');
const accessibilityScanResults = await new AxeBuilder({ page })
.withRules(['color-contrast']) // focus on contrast only
.analyze();
expect(accessibilityScanResults.violations).toEqual([]);
});
// Run in CI:
// npx playwright test accessibility.spec.tsQuick Check
Test your understanding of Tailwind CSS Mastery concepts from this lesson.
Lesson Recap
In this lesson you learned: WCAG AA requires 4.5:1 contrast for normal text and 3:1 for large text and UI components, Tailwind mid-range shades (400-500) often fail AA on white backgrounds, and color alone must never convey meaning — always pair color with icons or labels. Next up we explore focus indicators and keyboard navigation accessibility.
Frequently asked questions
Is the “Color Contrast and Readable Text” lesson free?
Yes — the full text of “Color Contrast and Readable Text” is free to read here on the web, and the Tailwind CSS Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Tailwind CSS Academy course, upgrade to CoddyKit PRO.
What will I learn in “Color Contrast and Readable Text”?
Use Tailwind's color shades to meet WCAG AA and AAA contrast ratios, and audit your palette for accessible text-on-background combinations. You practise Tailwind CSS Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Tailwind CSS Academy?
No prior experience is required. Tailwind CSS Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Color Contrast and Readable Text” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Tailwind CSS Academy lesson?
Yes. Every Tailwind CSS Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Color Contrast and Readable Text
- Focus Indicators and Keyboard Navigation
- ARIA Attributes and Screen Readers
- Accessible Form Components