Theme Accessibility: Contrast and Color-Blind Friendly

The thing people skip when picking a theme: looking good and being readable are two different problems. Codex theme accessibility comes down to concrete pairs, whether body text clears the background, whether neighbouring syntax colors separate, and whether the palette still works for somebody with a color vision deficiency. Here is what to measure, where to set the threshold, and how to check the result.

What a contrast ratio actually measures

A contrast ratio is the difference in luminance between two colors, written as a number between 21:1 and 1:1. Black on white is 21:1, and a color against itself is 1:1. It only looks at brightness, never hue, so two colors that look nothing alike can share the exact same ratio.

• Body text against the background: the pair you read most, and the only one that has to clear AA
• Comments against the background: usually the first to fall under the threshold, because comments are designed to recede
• Selected against unselected: too little separation and you keep selecting the wrong line
• Line numbers and indent guides: they do not change comprehension, but they change whether you can find your cursor
• The caret against the background: one pixel wide, so weak contrast means it might as well not be drawn

How the WCAG thresholds map onto a theme

WCAG gives three levels: AA asks for 4.5:1 on normal text and 3:1 on large text, and AAA pushes normal text to 7:1. Applying that to an editor is awkward, because syntax highlighting counts as neither normal text nor large text, and you read several hundred lines of it rather than one heading.

• Body text, strings, keywords: treat as normal text and aim at 4.5:1
• Comments: also normal text. Do not let them off because they are grey
• Tabs, scrollbars and other UI sitting on the background: 3:1
• Dividers and indent guides: no threshold, but anything under 1.5:1 is effectively not drawn
• AAA at 7:1 is worth chasing for body text alone. Chasing it everywhere flattens the palette

Color-blind friendly is not pastel

The common misreading is that color-blind friendly means avoiding red and green. Red-green deficiency is the most common type, but the fix is not to avoid a hue. It is to give colors a second axis of separation, which is lightness. Two syntax colors that differ only in hue collapse into one for a red-green viewer. Separate them by lightness and the problem disappears.

• Red-green deficiency affects hue judgments and leaves lightness judgments intact, which makes lightness the reliable second axis
• Red and green at the same lightness nearly overlap for a red-green viewer; lift or drop one and they separate
• Never encode state in color alone: an error needs an icon or a word, not just red
• Blue-yellow deficiency is rarer, and the same rule covers it
• Washing the palette into low-saturation pastels does not help, it drags contrast down with it

Four checks before you commit

• Turn the display brightness down and read body text again, which is where weak-contrast themes fall apart
• Squint at the screen: when two syntax colors merge, change hue rather than lightness
• Sample the rendered color and write the number down instead of eyeballing it
• Test both the light and dark scheme, since any slot you only filled in one falls back to the default
• Ask one colleague with a color vision deficiency to look, which catches in five seconds what you will never see yourself

Checking accessibility before you start editing beats redoing it afterwards. Colors live in /en/guides/customize, finished examples sit in the gallery at https://codex-skin-studio.shop/en/gallery, and the background on this tool is at /en/about.

Frequently asked questions