Every theme we build comes down to one quiet question: can you read the text. A background can be gorgeous and a syntax palette can be clever, but if the comments wash out against the editor or a keyword glows too bright to scan, the theme has failed at the only job that matters. Readability is whether the words actually come through, and it rests almost entirely on contrast, the difference between the text and whatever sits behind it. The good part is that you do not have to guess. Readability has numbers, and this is a short guide to the two that count, the WCAG 2 ratio and the newer APCA, plus how to read them without a headache.
The WCAG 2 Ratio
The first number worth learning is the WCAG 2 contrast ratio, the one baked into almost every accessibility checker and design audit. It compares the relative luminance of two colors, the text and the background behind it, and gives you a value that runs from 1 to 1, meaning no contrast at all, up to 21 to 1, which is pure black on pure white. The thresholds are easy to keep in your head. Normal body text wants 4.5 to 1 to pass the AA level and 7 to 1 to reach AAA. Large or bold text gets an easier bar, 3 to 1 for AA, because bigger shapes survive on less contrast.
This one ratio carried the web for years, and it still catches the worst mistakes. Pale grey text on a white card, the favourite sin of modern design, fails it on sight. If you only ever check one thing, check this.
But the ratio has a blind spot that matters a great deal for themes. It does not care about polarity. It hands you the same score whether your color is the ink or the page, even though dark text on a light background and light text on a dark background never read the same to the human eye. It also flatters the dark end of the range, so two deep colors can pass on paper while looking like one smear on a real screen. Anyone who has built a dark theme has felt that gap: the math says fine, the eye says mush.
APCA, the WCAG 3 Way
APCA is the answer to that blind spot, and it is the contrast model heading into WCAG 3. Instead of a flat luminance ratio it uses a perceptual model, tuned to how we actually read text at different sizes and weights, and it pays attention to which color sits on top. Its score is called Lc, for lightness contrast, and it runs roughly from 0 to about 106 with a sign attached. A positive number means dark text on a lighter background. A negative number means light text on a darker background.
Because APCA knows the direction, it gives you two different answers for the same pair depending on which color is the text. Put your brand color on white and you get one score. Put white text on that same brand color and you get another. That is not a glitch. It is the entire point, and it is exactly the call you make when you design an editor: is this hue the page, or is it the ink.
Both, Side by Side
We do not treat these two as rivals. WCAG 2 is the rule most audits and most clients still ask for, so it simply has to pass. APCA is the better read on how the text will actually feel, especially in the dark themes we ship the most of. So when we choose a foreground for a background, we look at both at once.
Take Codigrate Blue, our own #00BAFF. It is a bright, friendly cyan, and it makes a perfect teaching case. As text on a white page it fails badly. The ratio comes in low and the APCA score is weak, because a light color on a light background never gives the eye enough edge to grab. Make it the background instead, with dark text on a #00BAFF button, and it reads cleanly. The same color fails as ink on a white page yet works as the surface under dark text, which is the whole reason you cannot judge a color until you know which one is the ink.
The Takeaway
None of this needs to slow you down. Pick a foreground and a background, read the WCAG ratio and the APCA score, and nudge whichever color moves more easily until both clear the bar. It is the same pass we run on every theme before it ships, which is why the text stays readable long after the wallpaper stops being the thing you notice. For conversions, color schemes and a color blindness simulator alongside this check, open the color tool.
