Dark Mode Colors: Surface, Border, and Text Ratios That Actually Pass

Every number below is computed with the WCAG relative-luminance formula on sRGB values. You can verify any row in the Contrast Checker.

The canonical dark elevation stack, measured against itself:

Jumping the entire stack in one leap still only reaches 1.35:1. To hit 3:1 from #0B0D10 you would need a surface around #5E5E5E — a mid-gray that no longer reads as dark mode at all. Elevation and non-text contrast are mutually exclusive goals on dark surfaces. Choose elevation for depth, then add a border to carry the accessibility requirement.

The minimum neutral gray that reaches 3:1 on each dark surface:

The typical dark-mode border sits around #2A2F37 or #333A45. Measured against base, #333A45 gives 1.70:1 — decorative. It looks like a border and it reads as a border, and it fails. When the boundary is the only way to tell an interactive component from the page, you need the #5E5E5E-and-up column, and it has to get lighter as the surface gets lighter.

A border that passes on the page can fail inside a modal. #333A45 measures 1.70:1 on base but only 1.43:1 on raised. Borders have to be tokenized per surface, the same way text is.

Naive inversion — what breaks when you flip light-mode tokens onto #0B0D10:

The pattern: mid-tone tokens are the casualties. Near-black text inverts to near-white and stays fine. Saturated mid-tones designed to sit on white have nowhere to go — they were already darker than the midpoint, so on a dark surface they lose the contrast they had. Brand blue at #1D4ED8 fails the 3:1 non-text floor, which means a button in that fill has no reliably visible shape on a dark page.

The pure-black question, measured:

Moving from #000000 to #0B0D10 costs 1.4 points out of a 19-point ratio. That is noise. You keep an enormous surplus and you lose the halation effect where light text on true black appears to bleed for readers with astigmatism. Near-black is nearly free. The real reason to avoid #000000 is that it leaves no room underneath — there is no darker surface available for a sunken state.

Every mature design system tokenizes borders separately from surfaces, and the math above is why. Vercel's dark dashboard increments each nested panel by roughly 4% lightness, and the visible card edges come from a dedicated border token rather than the surface delta. Linear runs four surface levels (#111 → #191919 → #222 → #2A2A2A) with explicit border values on top. Both teams landed where the arithmetic forces you: surface deltas on dark backgrounds sit near 1.1:1, so structure needs a second mechanism.

GitHub's launch-day dark mode is the reference case for mid-tone failure. Secondary text shipped at #8b949e on #0d1117, which measures 6.15:1 — a clean AA pass for body text, and still the most-complained-about element in the release. The fix went two directions at once: a brighter default muted token (#9198a1, 6.5:1) and a separate "dark high contrast" theme with text at #f0f6fc (17.4:1). The lesson is the uncomfortable one: a passing ratio is not the same as a comfortable one. Mid-tone gray on near-black clears the arithmetic and still reads as washed out, because WCAG 2 does not model the polarity penalty that light-on-dark text carries. If your dark-mode muted token sits in the 5:1–6:1 band, users will complain even though your audit is green.

Notion's 2025-2026 dark rollout hit a hue problem, not a contrast problem. Their original surfaces were warm grays with an amber undertone, and blue links rendered on them skewed toward purple on some displays. Contrast was fine. Perceived hue was not. They moved to neutral grays (#1A1A1A, #252525) and re-measured every link token, landing on #6AB0F3 (7.6:1 on #1A1A1A). Undertone in your dark surfaces shifts the apparent hue of everything placed on them — settle the surface family before tuning accents.

Figma published the number that kills the inversion shortcut. Their Aug 2025 accessibility-tokens post reported 15 of 42 text tokens needing genuinely different values in dark mode. Not scaled, not inverted — different. Roughly 36% of a mature text token set cannot be derived mathematically, which is close to what the mid-tone analysis above predicts.

The perceptual trap underneath all of this: on dark backgrounds saturated colors appear to emit light (the Hunt effect), so accents read brighter than they measure. Designers respond by desaturating until it looks calm, which drops the measured ratio while the color still feels vivid. That is the mechanism behind most "it looked fine in Figma" dark-mode failures.

The 20-minute dark-mode measurement pass. Deliberately narrower than a full audit — it only chases the failures the elevation math predicts, which happen to be the ones tooling misses.

1. Eyedrop your real surface stack (5 min). Not the Figma values, the rendered ones. Semi-transparent overlays composite against whatever sits behind them, so a modal scrim over a card produces a surface value that exists in no token file. Screenshot the running app in dark mode and sample every distinct background: page, card, raised panel, modal, tooltip, plus each tinted status surface. Expect 6–10 real values where your tokens list 4.

2. Measure every border against every surface it lands on (5 min). This is the step almost no team runs. One border token across four surfaces is four different ratios. Build the row, then mark each cell as boundary (≥3:1) or decorative (below). Finally, check whether anything in the decorative column is the only thing defining an interactive control's edge. Those are your SC 1.4.11 failures.

3. Check focus rings against the lightest surface, not the darkest (3 min). Rings get colored against the page, then break inside modals. Measured against this stack:

Unmodified brand blue #2563EB clears 3:1 on the page and fails inside a modal at 2.79:1 — it passes where you check and fails where users tab. One step lighter (#3B82F6) holds across the whole stack. SC 2.4.13 also wants at least a 2px perimeter area, so a 1px ring at 3.1:1 is failing on both axes simultaneously.

4. Verify on OLED hardware at 40% brightness (5 min). Low-brightness OLED crushes the bottom of the range: the 1.08:1 gap between base and card, already invisible to the standard, becomes invisible to everyone. Pure-black halation shows up here too. No emulator reproduces either effect.

5. Force-colors sanity check (2 min). Toggle Windows High Contrast (forced-colors: active). Every surface delta collapses to system colors. If the UI becomes unusable, structure was living entirely in elevation.

What each method actually catches:

Automated tooling scans the DOM for text pairs. It does not know which border is load-bearing, and it cannot tell that a card edge is the only cue marking a clickable surface. The measured matrix is the only method that catches the elevation failure, and it is manual.

Pre-ship checklist for dark surfaces:

1. Real composited surface values sampled from the running app, not the token file
2. Every border token measured against every surface it appears on
3. No interactive component whose only boundary is an elevation delta
4. Focus ring ≥3:1 on the lightest surface it can appear on, with ≥2px perimeter
5. Muted text measured on card and raised, not only on base
6. Mid-tone brand accents re-picked for dark, not inverted or scaled
7. Error and warning text measured on their own tinted surfaces
8. Base is near-black rather than #000000, leaving room for a sunken state
9. Surfaces neutral gray unless every accent has been re-measured against a warm undertone
10. Verified on OLED hardware at 40% brightness and under forced-colors