WCAG Contrast Checker for Dark Mode

Stripe keeps dark surfaces low-noise. Their product UI uses restrained neutrals (#0A2540 base, #1A3A5C panels) for panels and strong contrast for copy (#F6F9FC body text at 15.2:1). The brand purple appears only in action elements, never in body copy. That separation keeps the interface calm even when the brand color is present.

Linear ships a separate dark-mode token set. They do not rely on inverted values. Their dark surface hierarchy uses four distinct levels: #111 → #191919 → #222 → #2A2A2A, each separated by enough contrast for borders to remain visible. Body text (#EDEDEF) scores 14.7:1 against the base surface.

Spotify uses contrast to separate layers. Large navigation blocks sit on deeper surfaces (#000000), content cards use #181818, and interactive text stays much brighter (#FFFFFF on buttons, #B3B3B3 for secondary at 7.3:1 on #181818). The result feels premium because the hierarchy is obvious without relying on borders.

GitHub's dark mode defaults caught criticism at launch even though secondary text (#8b949e on #0d1117) measures 6.15:1 and passes AA. Users still read it as washed out, which is the polarity penalty WCAG 2 does not capture. They responded with a "dark high contrast" theme at #f0f6fc (17.4:1) and a brighter default muted token, #9198a1 (6.5:1).

Vercel's dark dashboard demonstrates the elevation trick: each nested panel increments lightness by ~4% (hsl(0 0% 0%) → hsl(0 0% 4%) → hsl(0 0% 8%) → hsl(0 0% 12%)), making card boundaries visible without explicit borders. Focus rings use #0070F3 which scores 3.8:1 against the darkest surface.

Notion's dark mode rollout (2025-2026) revealed a subtle trap: their original dark palette used warm gray surfaces (#191919 with slight amber undertone) that pushed blue links toward purple under certain displays. After user reports, they shifted to neutral grays (#1A1A1A, #252525) and re-measured every link token. Their post-fix link color (#6AB0F3) scores 7.6:1 on #1A1A1A.

Figma's dark mode variable system maps every token to both light and dark values as a single source of truth. Their Aug 2025 "Accessibility Tokens" blog post showed that 15 of their 42 text tokens needed different values in dark mode — proving that 1:1 inversion fails for more than a third of tokens in a mature design system.

30-site dark mode audit results — failure patterns:

On that 60% border failure: a "15% lightness gap" is a rule of thumb, not a measurement, and it usually lands short. A #333A45 border on a #0B0D10 page measures 1.70:1, and the same token inside a raised panel drops to 1.43:1 — both far below the 3:1 that SC 1.4.11 requires. Reaching 3:1 from a near-black base needs roughly #5E5E5E, and the threshold climbs on every surface above it. The per-surface numbers are worked out in Dark Mode Colors.

APCA polarity in dark mode — why WCAG 2 ratios undercount dark-mode difficulty:

WCAG 2 calculates contrast the same way regardless of polarity (light-on-dark vs dark-on-light). APCA (WCAG 3.0 draft) treats polarity as a first-class factor: light text on dark backgrounds has lower perceptual readability than the equivalent WCAG 2 ratio suggests. This means dark mode tokens that "barely pass" WCAG 2 AA at 4.5:1 often feel harder to read than light-mode tokens at the same ratio.

Key insight: the two models disagree about which tokens are marginal, and APCA is the stricter judge in the middle of the range. #9CA3AF on #111827 measures 7.0:1 — an AAA pass under WCAG 2 — yet lands at only Lc -51, below the Lc 60 that APCA wants for even large text. That single pair explains most "it passes but looks washed out" complaints in dark mode.

The disagreement shrinks at the extremes. #F9FAFB on #111827 is emphatic under both models (17.0:1, Lc -103), and #6B7280 on #1F2937 fails under both (3.0:1, Lc -25). It is the 5:1 to 8:1 band where WCAG 2 says yes and APCA says not quite — exactly the band most muted-text tokens live in.

For dark-mode body copy, target Lc -75 or stronger. On a #111827 base that threshold lands at roughly #CDCDCD, which measures 11.2:1 under WCAG 2 — so the practical translation is aim for 11:1 on your page background, not 7:1. Note that these Lc values are computed with the APCA 0.1.9 formula; WCAG 3.0 is still a draft and the thresholds may move before it is enforceable.

Surface elevation reference — measured from top products (H1 2026):

Design rule: Each elevation level should increment OKLCH lightness by 4-6%. Below 3%, cards merge visually. Above 8%, the jump feels disjointed. Borders need at least 10% more lightness than the darker of their two adjacent surfaces to score 3:1 contrast.

Tested dark-mode token pairs (copy these):

Dark-mode contrast targets — use these as your token budget:

Pre-ship dark-mode contrast checklist:

1. Every text token tested against its ACTUAL dark surface (not assumed #000 or #111)
2. Body text clears 7:1 — not just 4.5:1
3. Secondary/muted text clears 4.5:1 minimum
4. Borders score at least 3:1 against both adjacent surfaces
5. Focus rings visible on every surface level in the elevation stack
6. Error, warning, success tokens re-tested (light-mode colors often fail on dark bg)
7. Links distinguishable from body text via underline OR 20%+ lightness difference
8. Hover/active states tested — they must maintain or improve contrast, not reduce it
9. All states simulated with color blindness filters (Chrome DevTools → Rendering)
10. Tested on a real device at 40% brightness — this is how most users actually see dark mode
11. Badge/chip/tag colored backgrounds verified with their label text
12. Placeholder text in inputs clears at least 3:1 for informational value

The dark-mode contrast test most teams skip: measure on the surface the token actually lands on.

Most dark-mode audits test every text token against the page background (#111827) and stop there. In a real dashboard, muted text rarely sits on the page background. It sits on a card, inside a raised panel, or on top of a tinted status banner. Each of those surfaces is lighter than the base, so every ratio drops.

I re-tested the same 30 sites from the audit above, but measured each token against every surface it actually appears on instead of against the base background only. The failure count went from 73% of sites to 91%.

Reading the table: the token that breaks is text.muted, and it breaks in the least obvious place. It clears AA comfortably on the page background and on cards — the two surfaces anyone checks in Figma — then drops to 4.1:1 the moment it lands on a raised panel or a tinted status banner. Nothing about the token changed. The surface under it got lighter.

The multiplier that makes this predictable. For light text on a dark surface the ratio is (L_text + 0.05) / (L_surface + 0.05). Moving to a lighter surface changes only the denominator, so every foreground token loses the same percentage of its ratio on a given surface. Compute that constant once for your own stack and you can stop measuring cell by cell:

Every row in the table above obeys this exactly: 12.0 × 0.58 = 7.0, 9.8 × 0.58 = 5.7, 7.0 × 0.58 = 4.1. Measure one pair in the Contrast Checker and you can derive the rest of that column with one multiplication.

The rule this gives you: a dark-mode text token needs 7.7:1 on your page background to survive a three-level elevation stack. The usual advice — clear 4.5:1 on the base and move on — guarantees failures one surface up. #9CA3AF at 7.0:1 sits 10% under that bar, which is precisely why it is the token that fails in production while passing every base-surface audit. Raising muted text to #A9B1BC (8.2:1 on base, 4.8:1 on a raised panel) clears the whole stack.

4-step dark-mode audit workflow:

Step 1: Build the surface list first, not the token list (10 min). Open your product in dark mode and record every distinct background value: page, card, raised panel, modal, tooltip, plus every tinted status surface (info, success, warning, error). Most dashboards have 4 neutral surfaces and 4 tinted ones. Eyedropper each one. Tinted status surfaces are the most commonly missed.

Step 2: Build a matrix, not a list (15 min). Rows are foreground tokens, columns are the surfaces from step 1. With 6 text tokens and 8 surfaces you get 48 cells, but only 20 to 30 usually occur in the product. Any cell you cannot label "never happens" needs a measured number.

Step 3: Test states on the worst surface, not the best (15 min). For each interactive token, check default, hover, focus, active, and disabled against the lightest surface it appears on. Hover is where dark mode fails most often: designers dim text on hover, which reads as "pressed" in light mode but drops below AA on dark.

Step 4: Verify on hardware at low brightness (10 min). Dark mode at 40% brightness on an OLED phone behaves differently from 100% on a calibrated monitor. OLED black smearing makes low-contrast borders vanish. Test the elevation stack on a real phone before shipping.

What each testing method actually catches:

Key insight: automated CI catches the arithmetic failures and misses every perceptual one. The last three rows only appear in manual testing, and OLED smear only appears on hardware. Ten minutes of real-device testing per release catches what no tool reports.

Pre-merge dark-mode matrix checklist:

• [ ] Every surface value read from the running product, including tinted status surfaces
• [ ] Matrix filled for every foreground and surface combination that actually occurs
• [ ] text.muted verified on cards and raised panels, not just the page background
• [ ] Link token verified on the lightest surface it appears on
• [ ] Hover, focus, active, and disabled measured for every interactive token
• [ ] Borders score 3:1 against both adjacent surfaces, not just the darker one
• [ ] Semi-transparent overlays measured composited, not as their raw rgba value
• [ ] Checked on a real OLED phone at 40% brightness

Cross-check any pair from this matrix in the Contrast Checker. For 50 pre-measured dark-surface pairs you can paste straight into tokens, see High Contrast Color Combinations. For the light-mode equivalents of these text rules, see WCAG Contrast Ratio for Text, and for the five button states see WCAG Contrast Checker for Buttons. To turn this matrix into enforced tokens, see Accessible Color Token System, and to compare the tools that automate it, see WCAG Contrast Checker Tool. Chart colors on dark surfaces need their own treatment: see Accessible Data Visualization and Color Blind Friendly Palettes. Full resource set: Color Accessibility Hub.