THE GITHTML FIELD GUIDE
Give an HTML reading document a deliberate dark appearance
Define text and background colors together, then provide a dark color palette through prefers-color-scheme when appropriate. Check links, borders, code samples, and embedded images in both appearances. Dark mode is an enhancement to a readable document, not a reason to rely on low contrast or hide distinctions encoded only by color.
Start with a complete palette
A common dark-mode failure comes from changing the page background but leaving individual components with hard-coded light colors. The result may include pale text on a white callout or a black diagram on a dark surface. Inventory the document's visible roles: body text, muted text, background, panel, border, link, and warning. Assign each role a deliberate pair of light and dark values.
For a static report, a small set of CSS custom properties can keep those decisions consistent. Avoid scattering arbitrary colors across inline style attributes. When a new component is added later, it should use the existing roles or explicitly introduce a new one. This makes appearance review a manageable task rather than a hunt through every paragraph.
Treat visuals as separate assets
Screenshots and exported diagrams do not automatically adapt to the surrounding palette. A white screenshot may be perfectly readable in a dark article if it has a clear boundary and an explanatory caption. Applying a blanket inversion filter can distort colors that have meaning, including warning states, data series, and product branding. Review visuals individually instead.
For diagrams you control, consider a neutral background and strong labels that work in both appearances. If separate versions are necessary, ensure they communicate the same information. Never make the dark version omit details simply to achieve a cleaner look. A reader changing appearance should not receive different evidence or a different conclusion.
Review states and exceptions
The sample establishes only broad page colors. Choose and check actual link, code, and callout colors for your content. Review visited links where relevant, and keep underlines or another non-color cue so links remain recognizable. If the document uses colored status badges, include the status word inside each badge.
- Check both appearances with the same document revision.
- Inspect every callout, table border, and diagram label.
- Confirm that warning meaning survives a grayscale view.
- Avoid claiming that a dark palette alone makes the document accessible.
:root { color-scheme: light dark; --paper: #fff; --ink: #202124; }
@media (prefers-color-scheme: dark) {
:root { --paper: #181a1b; --ink: #f0f1f2; }
}
body { background: var(--paper); color: var(--ink); }Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.