A dark UI looking accessible and actually passing a contrast check are two different claims, and the gap between them is where real bugs live. A full color-system audit on Mawu Dark Mode’s six themes found two genuine WCAG contrast failures that had shipped for multiple releases, neither one caught by eyeballing the result. Here’s what WCAG actually requires, and exactly how both bugs got past a design that looked fine.
What WCAG contrast actually requires
WordPress’s WCAG guidelines, like most web accessibility standards, are measured, not judged. Normal text against its background needs a contrast ratio of at least 4.5:1 under WCAG Success Criterion 1.4.3. Large text, meaning roughly 18-point or 14-point bold, and UI components like borders and form control outlines, get a lower bar of 3:1 under Success Criterion 1.4.11. Both numbers come from the same underlying calculation: convert each color to relative luminance, then compute (L1 + 0.05) / (L2 + 0.05) for the lighter and darker of the pair.
That’s a formula, not an impression. Two colors that look like they contrast fine to a designer’s eye can measure well under the threshold, and the only way to know for certain is to actually run the numbers, for the exact pair of colors used in the exact place they’re actually used together.
Bug one: the right token, checked against the wrong background
Mawu’s muted text color, used for secondary and de-emphasized text, was contrast-checked when the themes were first built, against the palette’s main background and surface colors. That check passed. What nobody re-checked was where text_muted actually gets used in practice: a disabled form field’s text, set against surface_alt, a slightly different tone one step removed from the color it had originally been verified against.
Once someone actually measured that specific pairing, five of the six themes failed, with the worst case measuring 3.19:1 against a 4.5:1 requirement, nowhere close. Only one theme happened to pass by accident. The color itself wasn’t wrong in the abstract. It had simply never been checked against the one background it actually renders on.
The fix was to raise all five failing themes’ muted text color until they cleared 4.5:1 against their real consumer, not the plausible-looking one from the original design pass. The lesson that’s worth generalizing past this one bug: a design token’s contrast is only ever verified for the specific pairing you actually tested, never for “this token” in the abstract. If a token gets reused somewhere new later, that’s a new pairing that needs its own check, not an inherited pass from a different background it happened to look fine against once.
Bug two: a color chosen for one job, reused for a different one
Each of Mawu’s six themes has one accent color, picked to pop as a foreground color against a dark background: a link, an icon, a highlighted label. That’s a real, specific design constraint, and the accent colors were chosen with exactly that job in mind.
The login screen’s primary button reused that same accent color as a solid fill, with white text implied on top of it. That’s a different job entirely: hosting light text at 4.5:1 requires the fill itself to be dark enough, and a color picked to be bright and legible as a foreground element is, by design, usually too light to do that. Measured directly, three of the six themes came in at roughly 2:1, about half the legal minimum, and none of the six cleared 4.5:1.
This one shipped across several releases before anyone actually measured it, because “the accent color on the button” reads as reasonable at a glance, the same way the muted-text bug did. The fix was to set the button’s text color explicitly to black rather than assuming white, since black clears 4.5:1 against every one of the six accent colors, verified the same way as the first bug: computed, not eyeballed.
Why both bugs share the same shape
Neither failure was a bad color choice. Both were a color that had been verified once, in one context, and then reused somewhere the original verification didn’t cover. A token passing a contrast check tells you about one specific pairing. It doesn’t tell you anything about a different pairing that token gets reused in later, even if the reuse looks perfectly reasonable at the time. The only way to catch that is re-running the actual computation for every real pairing in use, not trusting that a color which passed once will keep passing wherever it ends up next.
Both fixes are live across all six of Mawu’s themes, verified at or above their required thresholds using the same relative-luminance calculation described above. See all 13 themes for the actual palettes, or Mawu Dark Mode to see them in your own dashboard.