Contrast Ratio
对比度
Aliases:对比度文字对比度可读性对比WCAG 对比看不清contrast ratiocolor contrast
What is it
The luminance ratio between foreground and background — the measure of whether text can be read. WCAG 2.1 sets hard floors: 4.5:1 for AA body, 7:1 for AAA, dropping to 3:1 and 4.5:1 for large text. APCA refines this by weight and size against perception. Compute the ratio before picking colours; never sign off by eye.
Interactive playground
Try it. Make an informed choice.Loading lab…
✓ When to use
- Body copy, labels and button text must meet accessibility floors
- Text legibility must be re-verified after a theme switch
- Greyscale muted text silently drops below 3:1
✕ When not to use
- Decorative display type or pure graphics — non-text contrast rules apply instead
- Disabled control text — explicitly exempt in WCAG
- Mandating AAA everywhere and strangling the design space
Variants
AA body text
AA 正文
4.5:1 — the default floor for most UI
AAA
AAA 高标
7:1 — long-form and older audiences
Large text exception
大号文字豁免
≥24px or 18.66px bold drops the floor to 3:1
Implementation
color-mix()oklch()contrast-ratio()@media (prefers-contrast: more)The formula: convert sRGB to linear luminance Y, then (L1+0.05)/(L2+0.05). Lock body text at 4.5:1 and large text at 3:1. Do not fake hierarchy with opacity — use the ink-2 step instead. High-contrast themes come from prefers-contrast: more or a dedicated role table. Spot-check every text role pair before shipping, muted and line especially.
Platform API
WCAG 2.1APCAcontrast-ratio()In code
The exact names this thing goes by in each ecosystem — use the row that matches your project.
| Framework | Name |
|---|---|
| W3C | WCAG 2.1 — Contrast (Minimum) |
| W3C | APCA |
| CSS | contrast-ratio() The ratio function in CSS Color 5 |
Related concepts
Colour variables named by purpose, not hue: bg, surface, text, muted, accent, danger. Components consume roles only, so a theme switch re-points the mapping layer instead of touching components. Light, dark, high-contrast and brand skins are simply different value tables over the same roles.
FoundationUsed withStart from one base hue and generate an ordered ramp (50–900), then assign primary, secondary, accent and neutral roles. Steps advance by lightness rather than ad-hoc picks, so hover, disabled and border always have the right depth on hand. Name roles before hex values and themes stay swappable.
FoundationUsed withShadow depth expresses how far an element sits from the page: 0 rests flat, 1–2 lift, 3 and above become overlays. Each shadow stacks umbra, penumbra and ambient layers — higher levels mean larger, softer casts. Use elevation to describe stacking relations, never as ornament.
FoundationUsed with