Dark Mode Design Considerations for JSON Formatters

A good dark mode for a JSON formatter should do more than swap a white background for a black one. It should follow the user's system theme, keep keys and values easy to scan, preserve contrast for long reading sessions, and stay usable when someone enables higher-contrast or forced-color settings.

That matters more in a formatter than in a typical marketing page. Users stare at nested braces, repeated keys, validation errors, selection highlights, and line-based diffs for long stretches. If the theme is too dim, too saturated, or inconsistent across states, dark mode quickly becomes harder to use than light mode.

Start with system theme support

Current browsers support system-theme detection with prefers-color-scheme, and the companion color-scheme property tells the browser that your editor shell can render correctly in light and dark themes. That second piece matters because browser UI such as scrollbars, form controls, and other built-in surfaces can otherwise stay visually out of sync with your editor.

The practical pattern is simple: default to the system preference, then let the user explicitly switch to light or dark mode and persist that override. For a formatter, this avoids the common failure where the code pane is dark but the textarea, dropdowns, or scrollbars are still light.

:root {
  color-scheme: light dark;
  --bg: #ffffff;
  --surface: #f6f8fb;
  --text: #16202a;
  --muted: #5b6673;
  --key: #0f5bd8;
  --string: #9a4d00;
  --number: #0e7a4b;
  --literal: #7b3fe4;
  --error: #c62828;
  --selection: rgba(15, 91, 216, 0.16);
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #111418;
    --surface: #171c22;
    --text: #e6edf3;
    --muted: #9aa6b2;
    --key: #7cc7ff;
    --string: #ffb86b;
    --number: #8bd8a8;
    --literal: #c2a6ff;
    --error: #ff7b72;
    --selection: rgba(124, 199, 255, 0.22);
  }
}

[data-theme="light"] { color-scheme: light; }
[data-theme="dark"] { color-scheme: dark; }

Build a restrained palette, not a dramatic one

The fastest way to make a dark JSON formatter feel cheap is to use pure black backgrounds, pure white text, and overly bright syntax colors. A restrained palette is easier to scan for long periods and produces less visual vibration between adjacent tokens.

• Use a dark charcoal or deep slate background instead of #000000.
• Keep primary text slightly off-white so punctuation, braces, and commas do not glow.
• Reserve the brightest colors for the information users search for first, usually keys, active matches, and validation errors.
• Keep line numbers, indent guides, and secondary labels quieter than JSON content, but not so faint that they disappear on lower-quality displays.

If the formatter also shows a tree view, table view, or side-by-side diff, reuse the same semantic color tokens there. Dark mode feels much more reliable when the key color in the editor matches the key color in a collapsed tree node or inspector panel.

Design syntax highlighting for JSON specifically

Generic code themes are often a poor fit for JSON because JSON has a smaller token set and much heavier repetition. The challenge is not language breadth, it is scanability across deeply nested structures.

• Keys: Give property names the strongest structural color because users visually jump from key to key when tracing objects.
• Strings: Keep them distinct from keys even when both are quoted; the difference should be obvious at a glance.
• Numbers and literals: Use separate hues for numbers and for true, false, and null so type mistakes are easy to spot.
• Punctuation: Braces, brackets, commas, and colons should be readable but lower-emphasis than content tokens.
• Invalid regions: Do not rely on red text alone. Add underline, gutter markers, or inline messages so the error still stands out in low-saturation or forced-color environments.

Also think about states that are specific to formatters, not just editors: current line, hovered row, selected text, search results, copied state, folded nodes, and diff inserts or removals. Those states should remain distinguishable from normal syntax coloring.

Treat accessibility as part of the theme

Dark mode does not relax accessibility requirements. WCAG contrast rules still apply, and in practice dark themes often need more deliberate testing because low-contrast text can look acceptable to the author on a calibrated display while becoming muddy on an ordinary laptop.

• Keep normal-size text at least 4.5:1 against its background and large text at least 3:1.
• Make keyboard focus impossible to miss. A visible outline of about 2px with a strong color change is a safer choice than a subtle glow on a dark surface.
• If your formatter has sticky headers, toolbars, or error banners, keyboard focus should remain visible and not slide under those layers.
• Do not remove browser focus styles unless you replace them with something stronger.

Modern platforms also expose user preferences beyond light or dark mode. A formatter should respond cleanly when users request more contrast, and it should degrade safely in forced-colors mode rather than fighting the system palette.

@media (prefers-contrast: more) {
  .json-editor {
    border-color: currentColor;
  }

  .token-punctuation,
  .line-numbers {
    color: var(--text);
  }

  :focus-visible {
    outline: 2px solid currentColor;
    outline-offset: 2px;
  }
}

@media (forced-colors: active) {
  .json-editor {
    background: Canvas;
    color: CanvasText;
    border: 1px solid CanvasText;
  }

  .token-error {
    color: Mark;
    text-decoration: underline;
  }
}

Handle the states users actually hit in a formatter

Many dark-mode articles stop at background and token colors. That is not enough for a JSON formatter because real sessions involve validation, navigation, and utility actions.

• Selection: The selection color has to preserve legibility for both keys and values. Avoid opaque fills that wipe out syntax meaning.
• Search: Active and inactive matches need distinct colors, especially on large documents.
• Errors and warnings: Validation states should be visually separate from normal syntax colors and from search highlighting.
• Buttons and inputs: Copy, format, minify, validate, and download controls need hover, active, disabled, and focus states that are all visible on dark surfaces.
• Scroll position: Long JSON files make scrollbar visibility and current-location cues more important than in ordinary text areas.

If the product includes an inline diff, be especially careful with red and green on dark backgrounds. Those colors often pass a quick visual test but are hard to distinguish for some users, so pair them with icons, labels, or stronger background patterns.

Quick QA checklist before you ship

1. Switch the operating system between light and dark mode and confirm the formatter follows it by default.
2. Toggle an explicit in-app theme override and verify that it wins over the system preference.
3. Test valid, invalid, minified, and deeply nested JSON so token colors and error states all remain readable.
4. Tab through every interactive element and check that focus is still obvious on the darkest surface.
5. Check selected text, search matches, diff states, copied-state toasts, and disabled buttons.
6. Enable higher-contrast or forced-color settings and confirm the app stays usable without custom shadows.
7. Open the page on desktop and mobile widths so line numbers, wrapping, and toolbars do not collapse into noise.

Conclusion

The best dark mode for a JSON formatter feels quiet, predictable, and structurally clear. It respects system theme settings, keeps token meaning obvious, preserves accessible contrast, and still works when the user needs more contrast than your default palette provides. If you design for those conditions first, dark mode becomes a real usability feature instead of a visual checkbox.