颜色对比度与易读文本
使用 Tailwind 的颜色层级满足 WCAG AA 和 AAA 对比度要求，并检查调色板中的无障碍文字与背景组合。
颜色对比度与易读文本 是 CoddyKit 上的免费 Tailwind CSS Academy 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Tailwind CSS Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Tailwind CSS Academy 课程共包含 4 节课。
本课时的部分内容尚未翻译，以英文显示。
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.
常见问题解答
「颜色对比度与易读文本」课时是免费的吗？
是的 — 「颜色对比度与易读文本」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Tailwind CSS Academy 课程的其余内容，请升级到 CoddyKit PRO。 Tailwind CSS Academy 课程共包含 4 节课。
「颜色对比度与易读文本」这节课中我会学到什么？
使用 Tailwind 的颜色层级满足 WCAG AA 和 AAA 对比度要求，并检查调色板中的无障碍文字与背景组合。 你通过在浏览器中直接运行的动手代码来练习 Tailwind CSS Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Tailwind CSS Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Tailwind CSS Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。
「颜色对比度与易读文本」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Tailwind CSS Academy 课中编写并运行代码吗？
能。每节 Tailwind CSS Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。
此课程中的所有课时
- 颜色对比度与易读文本
- 焦点指示器与键盘导航
- ARIA 属性与屏幕阅读器
- 无障碍表单组件