Codex Theme Contrast: A Practical Guide for Readable Skins

What contrast ratio actually measures

Contrast ratio compares the relative luminance of two colors. It ranges from 1:1, identical, to 21:1, black and white. The WCAG minimum for normal text is 4.5:1; large text can be 3:1. UI components and focus indicators need 3:1 against their adjacent colors.

The ratio is a property of the pair, not of the text color alone. The same gray can be perfectly readable on a warm surface and invisible on a dark image. That is why the studio measures against the actual surface you chose.

Dark themes: avoid the extremes

Pure black and pure white create the maximum ratio, and that is often the problem. On OLED, white text on black can produce halation, a glowing edge that makes small type feel blurry. A near-black surface and slightly dimmer text are easier to read for long sessions.

Use a surface around #121316 to #1c1c1e and text around #f5f0e8 rather than #ffffff. The ratio is still comfortably above 4.5:1, but the visual shock is lower. Panel separation comes from a slightly lighter surface and a subtle border, not from shadows.

Test the theme in the room where you actually work. A near-black surface that feels elegant at night can turn into a mirror in daylight, and a warm off-white that looks clean on a laptop can glare on a calibrated monitor. Contrast is measured, but comfort is contextual.

Light themes: paper, not white

Pure white maximizes glare. A warm off-white such as #f5f0e8 keeps the page calm and still gives slate text plenty of contrast. The risk in light themes is the opposite of dark themes: borders and secondary text become too faint.

Test disabled buttons, placeholders and the border between the sidebar and the task. If those disappear, the theme is not minimal; it is unfinished. Raise the border contrast before you add more decoration.

Diff colors need a separate test

Added and removed lines are not normal text. They carry meaning through color, which makes them a color-vision accessibility problem. Green and red are the default, and they are also the pair many people struggle to distinguish.

Keep enough lightness difference between the two, add a non-color cue such as a left border or a background tint, and test on the actual surface. A green that passes text contrast can still disappear against a saturated background.

A quick simulation helps: view the diff through a deuteranopia filter and ask whether added and removed still differ. If the only difference is hue, add a left border, a plus or minus glyph, or a background tint. Color should reinforce meaning, not carry it alone. The goal is a diff that survives a black-and-white screenshot as well as a color one.

The accent is a control color

An accent is not a decoration. It marks primary actions, links and focus. That means it needs 3:1 against the surface for UI components, and it should not be used for large blocks of text.

A bright accent looks good in a thumbnail and becomes tiring across a sidebar. Choose one accent, use it sparingly and let the ink scale carry the rest of the hierarchy.

One practical test is to shrink the interface to 80% and look at a link, a primary button and a focused field. If color is the only thing separating them, the hierarchy is too thin; add weight, spacing or a border before you raise saturation.

How to measure without fooling yourself

Measure the rendered pair, not the intended pair. Antialiasing, transparency and the background image all change the effective color. If the panel is 88% opaque over a photo, the text is not sitting on the panel color; it is sitting on a blend.

The CodexSkin studio runs the same WCAG calculation before it lets you export, and the checker on this page uses the same formula. That is deliberate: you should be able to audit our presets instead of trusting a screenshot. If a preset fails your numbers, change it or do not use it.

The studio's checker uses the chosen surface values, which is the right first pass. The second pass is visual: a dense diff, a long paragraph and a low-brightness screen. If the ratio passes but your eyes hurt, trust your eyes and adjust.

A short contrast checklist

If a theme passes all six, it is probably comfortable. If it passes the numbers but fails the visual test, the problem is usually contrast uniformity: everything is equally loud, so nothing has hierarchy.

• Normal text is at least 4.5:1 against the effective surface.
• UI controls and focus rings are at least 3:1.
• Disabled and placeholder text are still readable.
• Diff additions and removals differ by more than hue.
• The accent is used for controls, not body copy.
• The theme was tested at low brightness and in a bright room.

FAQ