How Should You Choose Colors for a Developer Website? How to Make Code and Text Easy to Read

TIPS

On a developer website, readers often alternate between written setup instructions and code they might adapt for their own work. Faint explanatory text or a code sample with too many competing colors can make it difficult to follow the right line. Using a fictional input-validation tool as an example, this guide shows how to give prose and code clear, readable roles within one color scheme.

Separate explanatory text from code and give each highlight a purpose

Start with a light background and dark text for the explanations. Rather than giving every instruction, caution, or heading a new color, organize the content using heading sizes, spacing, and numbered steps. Show links within the prose with underlines as well as a distinct link color, so it is clear which words are actionable.

A code block is an area that displays several lines of programming code together. Using a different background for that area helps readers recognize where the example starts. Keep regular code characters light against a dark background; use a slightly quieter color for comments, lines written to explain the code without executing, and another light color for keywords, words with a defined role in the programming language. Coloring code according to these roles is called syntax highlighting.

The goal is not to introduce as many colors as possible. Preserve indentation, punctuation, and line spacing, and do not rely on hue alone to distinguish a comment from a keyword. Evaluate the foreground colors against the actual background of the code block, separately from the body text.

A seven-color palette for an input-validation code example

Imagine a page explaining how to use a fictional tool that checks input values. A HEX code represents a color with a hash sign (#) followed by six hexadecimal characters. Assign these colors to specific roles:

Page background: cool off-white #F7F9FC — explanations and setup instructions.
Body text and headings: dark blue-gray #253448 — written guidance and numbered steps.
Code-block background: deep navy #172635 — the surface behind the code example.
Regular code text: near-white #F1F5F9 — function names, punctuation, and ordinary code.
Comments: light blue-gray #B6C4CC — explanatory lines inside the code.
Keywords: soft amber #F6C981 — language keywords such as const and if.
Links and action buttons: deep blue #1A6086 — links to more detail and the “Copy code” button.

For instance, show explanatory text in #253448 on #F7F9FC, followed by a code example on #172635. Use #F1F5F9 for the ordinary code characters, #B6C4CC for the comment, and #F6C981 for the keywords. These colors help readers recognize different roles within the same block.

This sample is only for demonstrating the color scheme. Its functions are fictional.

// Example function, not a real implementation
const result = checkInput(value);
if (result.ok) {
  showResult(result);
}

Display underlined explanatory links in #1A6086, which provides approximately 6.50:1 contrast against the #F7F9FC page background. The “Copy code” button can use #1A6086 as its background and #F1F5F9 for its label, reaching approximately 6.26:1. When copying succeeds, give textual feedback such as “Copied” rather than indicating success only through a color change.

A contrast ratio measures the relative brightness difference between adjacent colors. Body text #253448 on #F7F9FC has a ratio of approximately 11.97:1, while regular code text #F1F5F9 on navy #172635 reaches about 14.04:1. Comments #B6C4CC on navy reach about 8.61:1, and keywords #F6C981 on navy reach about 9.96:1. All four exceed the 4.5:1 requirement for normal-size text at Level AA of the Web Content Accessibility Guidelines (WCAG) 2.2. The code-block surface itself contrasts with the overall page background by about 14.59:1.

Check the details that help readers avoid misreading code

Test text size and line wrapping. On a phone, forcing long code lines to wrap can make indentation and punctuation harder to follow. Allow horizontal scrolling inside the code block when necessary, while keeping the explanatory prose readable with normal line wrapping.

Do not rely on color to communicate code meaning. Preserve the comment markers and familiar syntax. If you present differences between two versions of code, include “Added” or “Removed” labels or corresponding symbols as well as color. Syntax highlighting helps people scan code, but it should not be the only way to communicate meaning or an error.

Check links and copy controls in the actual interface. Use underlines or recognizable button shapes for actions, and preserve keyboard-focus indicators—the visible outline showing which control currently receives keyboard input. Every time you add or adjust another syntax color, recheck that token against the real code-block background. A developer site benefits most from clear distinctions between the prose, the code, and the available actions, rather than decoration for its own sake.