WCAG contrast levels
The WCAG 2.1 contrast ratio is calculated from the relative luminance of two colors using the formula(L1 + 0.05) / (L2 + 0.05), where L1 is the lighter color’s luminance. Ratios range from 1:1 (identical colors) to 21:1 (black on white).
AAA — 7:1 or higher (enhanced)
AAA — 7:1 or higher (enhanced)
The highest WCAG level. Text at this ratio is highly readable for users with low vision. Recommended for body text and anything users will read at length.
AA — 4.5:1 or higher (standard)
AA — 4.5:1 or higher (standard)
The minimum required ratio for normal-sized body text under WCAG 2.1 Level AA compliance. This is the baseline for most accessibility requirements.
AA18 — 3:1 or higher (large text only)
AA18 — 3:1 or higher (large text only)
Acceptable only for large text (18pt+ regular or 14pt+ bold). Not sufficient for small body text or UI labels. Shown in the checker as
aa18.Fail — below 3:1 (not accessible)
Fail — below 3:1 (not accessible)
The color combination does not meet any WCAG threshold. Avoid using these color pairs for text, icons, or any content that needs to be read. Shown in the checker as
fail.Two views
When 2 or more colors are in your palette, the contrast checker shows a tab bar with two views. Press Shift+K to cycle between them without using the mouse.The tab bar fades in automatically once you have 2 or more colors. With a single color, only the “vs backgrounds” view is available.
vs backgrounds
Each palette color gets a card showing its contrast against three standard theme backgrounds:| Background | Hex value | Description |
|---|---|---|
| light | #f5f5f5 | Near-white surface |
| gray | #777777 | Mid-tone surface |
| dark | #1a1a1a | Near-black surface |
excellent on light · readable on gray · not suitable on darkThis sentence is built from
describeContrast in src/helpers/contrast.ts, which groups backgrounds by quality tier and joins them into readable prose. If a color passes AAA on every background, it outputs “excellent readability on all backgrounds”. If it fails every background, it outputs a warning to adjust the color.
vs each other
A matrix showing the contrast ratio between every pair of colors in the palette. Each cell in the upper triangle of the matrix displays the ratio and WCAG level for that pair. Diagonal cells (a color against itself, always 1:1) show—.
This view is useful for checking whether colors you plan to use together — as text and background, for example — have enough contrast between them.
Using the contrast checker to build accessible palettes
Check every color against light and dark
A palette typically needs at least one color that passes AA on a light background (for dark text on light UI) and at least one that passes AA on a dark background (for light text on dark UI). Look for
aa or aaa badges.Identify problem colors
Colors with
fail on all backgrounds are unsafe as text colors anywhere. Either adjust their lightness in the color editor or use them only as decorative fills — not text or icons.Check color pairs
Switch to “vs each other” with Shift+K and verify that any colors you intend to layer (background + foreground, button + label) meet at least the
aa threshold.Iterate
Use the color editor or color variations to adjust lightness until all critical pairs meet your target level. The contrast checker updates in real time.
Keyboard shortcuts
| Shortcut | Action |
|---|---|
| K | Toggle contrast checker open / closed |
| Shift+K | Cycle between “vs backgrounds” and “vs each other” tabs (requires 2+ colors) |
Related
Color editing
Adjust individual colors to hit contrast targets.
Color variations
Generate tints, shades, and tones to find accessible variants.
Color blindness simulation
Test how your palette looks under different vision types.