Dark mode color guide

What dark mode color design is

Dark mode color design is the practice of building a complete interface palette for dark backgrounds. It includes page backgrounds, surfaces, raised panels, text, muted text, borders, dividers, icons, focus indicators, links, buttons, form controls, semantic states, charts, shadows, images, and theme tokens.

A dark theme is successful when it feels comfortable in low-light conditions, preserves hierarchy, remains readable, supports the brand, respects user preferences, and stays accessible. It should feel like the same product in a different lighting condition, not a separate product with a decorative black skin.

Why inversion is not enough

Automatic inversion can produce a first draft, but it rarely produces a polished dark theme. A light interface often relies on subtle gray borders, dark shadows, pale backgrounds, high-chroma accents, and brand colors chosen for white surfaces. When those values are flipped, hierarchy and meaning can collapse.

Inversion also affects images, logos, charts, disabled states, shadows, focus rings, code blocks, maps, illustrations, and semantic colors. A red error value that works on white may become too loud on charcoal. A pale blue focus ring may disappear on a tinted dark panel. A brand yellow may fail as button text or glow against a near-black background.

Start with a surface ladder

The surface ladder is the foundation of dark mode. It defines the difference between the page background, base panels, raised cards, controls, hover states, selected states, overlays, modals, and tooltips. Without it, a dark interface becomes a flat field of nearly identical rectangles.

A common approach is to use near-black for the page, then slightly lighter or cooler surfaces for panels and raised elements. The steps should be visible enough to support scanning, but subtle enough that the interface still feels calm. In dense software, the surface ladder often matters more than the accent color.

Recommended dark surface roles

Exact values depend on brand, product density, display quality, and desired mood, but the role structure is consistent. Name surfaces by use rather than by literal color so they can adapt across light, dark, high contrast, and future themes.

Tune text for readability and comfort

Readable text is the most important dark-mode color decision. WCAG contrast thresholds still apply, but a dense interface can technically pass while feeling harsh if every paragraph uses pure white on pure black. Many mature dark themes use near-white primary text, softer secondary text, and carefully tested muted text.

Avoid making muted text so quiet that it becomes decorative. Labels, metadata, helper text, placeholders, disabled text, captions, breadcrumbs, tab labels, timestamps, and chart labels all need to be readable enough for their job.

Contrast in dark mode

Contrast is not optional in dark mode. Text, icons, buttons, input boundaries, focus indicators, chart marks, and status components need enough contrast against the surface where they actually appear. Do not check a token only against the page background if it will be used on cards, tinted panels, gradients, or images.

Dark themes also need real-state testing. The normal state might pass, while hover, active, disabled, selected, loading, error, warning, and focus states fail. This is common when teams lower contrast to make the interface feel softer.

• Check primary text, secondary text, muted text, and disabled text on every surface role.
• Check button text on primary, secondary, danger, warning, success, and ghost button backgrounds.
• Check links, focus rings, input borders, selected rows, checkboxes, radio buttons, toggles, and slider handles.
• Check chart labels, legends, gridlines, map labels, and data marks separately from normal UI text.
• Check overlays, drawers, modal scrims, skeleton loaders, and toast notifications.

Control chroma and saturation

A color that feels balanced on white can feel electric on a dark surface. This is why dark mode often needs lower chroma for large fills, softer tints for backgrounds, and separate accent values for text, borders, and filled controls.

Use vivid colors intentionally. A saturated blue focus ring, red danger button, or green success dot can be useful because it attracts attention. The problem starts when large panels, backgrounds, charts, and decorative blocks use the same vivid color for too much area.

Use perceptual color spaces when possible

Simple hex edits and HSL lightness changes can create uneven steps in dark palettes. A color ramp may look balanced in code but jump visually from one step to the next. Perceptual color spaces such as Lab, LCH, OKLab, and OKLCH can make dark-mode ramps more predictable because they are designed around how color differences are perceived.

You do not need every production token to be authored by hand in OKLCH, but it is useful for palette creation. Build candidate ramps with more even perceived lightness and chroma, then test the actual rendered colors in browsers and design tools.

Semantic colors need separate dark-mode ramps

Success, warning, error, danger, info, selected, new, promoted, disabled, and destructive colors often fail when reused from light mode. Dark mode changes the perceived brightness and urgency of those colors, so each semantic family needs its own foreground, background, border, icon, and filled-control values.

This is especially important for errors and warnings. A pale red error background may vanish on a dark card, while a saturated red panel may feel alarming in a context that only needs mild correction. Tune severity through role and scale, not hue alone.

Focus rings and keyboard states

Dark mode often exposes weak focus styling. A focus ring that is visible on white may disappear on charcoal, tinted cards, image backgrounds, or saturated buttons. Keyboard users need a clear focus indicator on every interactive element.

Use a focus token that has strong contrast against the component and the surrounding surface. If one ring color cannot work everywhere, use a layered focus style: an inner ring, an outer ring, offset, outline, or shadow that adapts by component role.

• Check focus on dark page backgrounds, raised cards, tinted panels, primary buttons, danger buttons, disabled-adjacent controls, and image overlays.
• Do not rely only on a subtle glow. Make the active focus boundary geometrically clear.
• Ensure hover, focus, active, and selected states are visually different from each other.
• Test keyboard order and focus visibility together. A beautiful ring is not enough if it is clipped by overflow.

Borders, dividers, and elevation

Light themes often use shadows for elevation. Dark themes can use shadows too, but a black shadow on a near-black background may be invisible. The more reliable dark-mode elevation toolkit is surface lightness, border contrast, subtle glow, spacing, and layer order.

Borders deserve explicit tokens. A border that is perfect on surface-base may disappear on surface-raised or become too loud on surface-page. High-density dashboards, tables, code editors, forms, and settings screens need particularly careful divider tuning.

Forms and native controls

Forms are where dark mode often breaks. Inputs, selects, textareas, checkboxes, radio buttons, sliders, toggles, validation messages, placeholders, autofill states, and disabled states all need real dark-mode values.

CSS color-scheme can also affect native form controls, scrollbars, and built-in UI colors. If a page supports dark mode, declare the intended color schemes so the browser can render supported native controls appropriately. Then still test the actual controls in target browsers.

Images, logos, and illustrations

Dark mode is not only CSS colors. Images, logos, icons, screenshots, illustrations, maps, and product photography may need separate assets or treatment. A logo built for white backgrounds may need a reversed version. A screenshot with a white UI can create a bright block inside an otherwise comfortable dark page.

Do not dim every image automatically. Dimming can reduce clarity, distort brand colors, and make people look unnatural. Instead, decide by asset type: transparent logos, UI screenshots, editorial images, decorative illustrations, and data visuals each need different rules.

• Provide full-color, one-color, and reversed logo variants.
• Test transparent PNG and SVG marks on every dark surface where they appear.
• Use dark-mode screenshot variants when the surrounding page is dark.
• Add subtle borders or containers around light images so they do not feel pasted onto the page.
• Avoid applying a global opacity filter to meaningful images, charts, or product photos.

Charts and data in dark mode

Charts need special attention because dark mode changes how gridlines, labels, legends, data marks, and categorical colors are perceived. A palette that is distinguishable on white can become muddy on charcoal, while a high-saturation chart can feel noisy in a dark dashboard.

Use lighter labels, quieter gridlines, sufficient mark contrast, and direct labeling where possible. Sequential scales, diverging scales, and categorical palettes should be tuned for the actual chart background rather than copied from the light theme.

CSS support for dark mode

Modern CSS gives teams several ways to implement dark mode. The prefers-color-scheme media feature can respond to the user preference. The color-scheme property tells the browser which schemes an element supports, which can affect built-in rendering such as controls and scrollbars. CSS custom properties can hold theme tokens. light-dark() can choose between two colors when the used color scheme is known.

The most maintainable approach is usually token-first. Define semantic tokens such as --color-surface-page, --color-text-primary, --color-border-subtle, --color-action-primary, and --color-status-danger. Then assign different values for light and dark contexts. Components should consume tokens, not hard-code one-off dark values.

Respect user preference without trapping users

Dark mode should usually respect the system preference by default, but many products also need an explicit theme setting. A user may prefer dark mode at night, light mode in bright environments, or a specific theme for accessibility reasons. A good theme system can support system, light, dark, and sometimes high-contrast modes.

If the product includes a manual setting, make the choice persistent and easy to change. Avoid theme switches that flash through the wrong theme on page load. This is often solved by setting an early class or data attribute before the main CSS renders.

• Provide system, light, and dark options when the app has persistent user accounts or long sessions.
• Avoid hiding the theme setting deep inside account preferences for products used at night or for long reading sessions.
• Persist the chosen theme without causing a flash of the wrong theme.
• Do not override forced-colors or high-contrast user settings unless there is a tested reason.

Dark mode and accessibility beyond contrast

Dark mode accessibility is broader than a contrast number. People use dark themes for comfort, migraine sensitivity, low-light reading, battery preference, visual focus, and personal taste. Others find dark themes harder to read, especially with thin type, astigmatism, bright accents, or low-quality displays.

This means dark mode should be optional when possible and tested across real content densities. Long-form reading, dense tables, code editors, dashboards, forms, map views, and marketing pages each create different accessibility risks.

A practical dark-mode workflow

A reliable workflow starts with roles, not colors. If the team starts by choosing a charcoal background and a blue accent, the system will quickly run into missing states. Instead, list the UI roles, assign candidate values, test them in real components, and adjust in context.

• Inventory every color role in the light theme: surfaces, text, borders, actions, semantic states, charts, focus, overlays, and media assets.
• Create dark-mode surface roles first, including page, base, raised, hover, selected, overlay, and input surfaces.
• Define text and icon roles for primary, secondary, muted, disabled, inverse, and on-accent foregrounds.
• Tune brand accents and semantic colors separately for dark backgrounds.
• Build sample screens with real content density, not only isolated swatches.
• Check contrast for text, icons, borders, focus rings, controls, and chart elements.
• Test light mode, dark mode, system preference, forced-colors or high-contrast modes where relevant, and real device brightness.
• Document the final values as tokens and include usage rules for components.

Dark-mode token structure

Tokens keep dark mode maintainable. Avoid naming tokens after their current appearance, such as dark-gray-2, when the token actually means a card surface or muted text. Role names make it possible to change values without rewriting components.

Common dark-mode mistakes

Most dark-mode problems come from treating it as a finish layer instead of a system. A site can look impressive in a static mockup and still fail in forms, data tables, charts, focus states, or long reading contexts.

• Inverting the light theme and shipping the result without role-level testing.
• Using absolute black and pure white everywhere, then wondering why the interface feels harsh.
• Creating only one dark surface and relying on invisible shadows for elevation.
• Leaving muted text, disabled text, placeholders, and metadata below comfortable readability.
• Copying light-mode brand and semantic colors without reducing chroma or tuning lightness.
• Using color alone for errors, warnings, selected states, required fields, or chart meaning.
• Forgetting focus rings, hover states, active states, form controls, scrollbars, and autofill.
• Dimming images globally instead of creating asset-specific dark-mode rules.
• Hard-coding component colors instead of using theme tokens.
• Ignoring forced-colors, high contrast, and user preference settings.

How Hue Codex supports dark-mode work

Hue Codex can help turn dark-mode decisions into real values. Use the picker and converter to inspect exact colors, the tint and shade tools to explore ramps, the contrast checker to test foreground and background pairs, the color blindness simulator to check distinguishability, and the CSS tools to export ready-to-use values.

The most useful workflow is iterative: choose candidate tokens, test them in a real component, adjust lightness and chroma, retest contrast, then document the values as role-based tokens. Dark mode gets good by testing the actual interface, not by admiring isolated swatches.

Try it in Hue Codex

Use the free tools to test the idea immediately: pick a color, convert it, generate harmonies, build tints and shades, check contrast, and export practical CSS or palette data.