Applying a Dark Mode visual direction

You are applying Dark Mode to an existing web interface. Preserve the product’s purpose and content; design a complete dark appearance with its own surface, text, color, image, and state decisions rather than inverting a light theme.

What this means here

Dark Mode uses a dark neutral ground, a tonal elevation ladder, softened text, and rebuilt accents that remain legible without becoming neon. Surfaces nearer the viewer become lighter. Images and charts keep their meaning. The result should support sustained low-light use while retaining clear hierarchy and discoverable controls.

Recommendations

• Start with a dark grey base so elevated surfaces have room to step lighter.
• Name surface, text, border, accent, success, warning, and error roles semantically.
• Use luminance and fine borders for depth; do not make a dark shadow carry the hierarchy.
• Rebuild accents for the dark background and repeat state meaning with labels or symbols.
• Use technical typography and compact modules when the product domain benefits from them, but keep body text readable.
• Leave content imagery un-inverted; attenuate only when it improves the surrounding composition without changing meaning.
• Measure normal text at 4.5:1 or better and aim higher for small text where practical.
• Keep focus, hover, selected, and error states visible against every surface.

Avoid

• Pure black as the only base, pure white body text, or a light theme’s accents copied unchanged.
• Elevation expressed only by shadow.
• Inverted images, charts, or illustrations.
• Neon glow used as a substitute for hierarchy.
• Semantic meaning carried by hue alone.
• Real credentials, repository names, or operational metrics in a fictional specimen.

A working order

1. Identify the product’s low-light tasks and the content that must remain prominent.
2. Define base, workbench, elevated, and focused surface roles.
3. Define softened text, border, and divider roles against each surface.
4. Re-derive accent and semantic state colors for the dark ground.
5. Establish the main information grid and its compact utility modules.
6. Add the product’s data, command, or content layer before decorative effects.
7. Keep imagery and charts semantically intact; use an overlay only if needed.
8. Add labels, symbols, and states so color is never the only signal.
9. Measure contrast on normal text, small labels, and state treatments.
10. Test the narrow composition and remove any glow, shadow, or density that obscures hierarchy.

How to check your own work

Inspect each stacked surface in grayscale: is the nearer surface lighter? Measure text, accents, and states against the actual surface below them. Check the interface with images present, not just empty panels, and confirm that a user can identify status without hue. If every layer is the same charcoal or every state glows, the dark system is not yet doing enough structural work.

Dark Mode — Specification

Definition

Dark Mode is a complete interface appearance built on a dark neutral ground. It uses a stepped luminance system for elevation, softened text, mode-aware accents, and intact content imagery. It is not a light interface with colors inverted.

Core principles

• Darkness is a surface system. Base, workbench, elevated, and focused surfaces have deliberate relationships.
• Elevation is luminance. Raised layers become lighter; shadow is supporting detail, not the separator.
• Color is semantic. Accents and states are rebuilt for the dark ground and named by role.
• Contrast is strong and comfortable. Compliance is measured without treating maximum white-on-black contrast as the aesthetic goal.
• Content keeps its meaning. Images, charts, and illustrations are not inverted to match the shell.

Visual characteristics

• Charcoal base with slate workbench and subtly lighter focused modules.
• Off-white text, fine borders, and technical mono for commands or values.
• Cyan, amber, green, or red used sparingly as labelled semantic states.
• Dense developer-tool modules: command strip, run summary, telemetry, and status.
• Content visuals left intact, with no decorative black shadow doing the structural work.

Rules

1. Use a dark grey base. Pure black removes the elevation runway. Acceptance criterion: The base surface is not #000000 and has a relative luminance between 0.02 and 0.08.
2. Build a luminance ladder. Layers must remain distinguishable in low light. Acceptance criterion: Every elevated surface that remains stacked has a higher relative luminance than the surface beneath it; no layer relies primarily on shadow.
3. Soften primary text. The brightest value is reserved for emphasis. Acceptance criterion: Body text is not pure white and its computed contrast against its surface is at least 4.5:1.
4. Rebuild accents for darkness. Saturation does not survive unchanged from light mode. Acceptance criterion: Each accent is assigned a semantic role, measures at least 4.5:1 where it carries text or a state label, and is not the only state cue.
5. Keep small text comfortably strong. Dark does not excuse weak hierarchy. Acceptance criterion: Normal text measures at least 4.5:1; small or secondary text is reviewed against the 7:1 quality target where practical.
6. Preserve content imagery. The dark shell does not rewrite the data. Acceptance criterion: No image, illustration, or chart uses filter: invert; any attenuation is an overlay that leaves the underlying meaning intact.
7. Make developer-tool density legible. Compactness must have structure. Acceptance criterion: The primary view exposes a labelled command/run area and at least one labelled data or status module without relying on hover.
8. Keep semantic parity. Status is more than a color chip. Acceptance criterion: Success, warning, and error states each have a text label or symbol plus a semantic color treatment.
9. Budget effects. The dark surface should not become a neon stage. Acceptance criterion: No more than one preview-only motion or glow treatment is active at a time, and the static state communicates the same information.

Avoid

• Pure-black base surfaces, pure-white body copy, copied light-theme accents, and shadow-only elevation.
• Inverted imagery, unlabeled color states, and glow used to compensate for missing structure.
• Fictional operational data presented as real.

Acceptance criteria

• Base is dark grey, not pure black, and leaves room for elevation.
• Stacked surfaces step lighter toward the viewer.
• Body text and state labels meet their contrast floors.
• Accents are semantic, rebuilt for darkness, and not the only state cue.
• Images and charts are not inverted.
• A labelled command/run module and data/status module are visible without hover.
• Effects stay within a small preview-only budget and have a static equivalent.

Blocking failures

• Stacked layers are separated only by an invisible dark shadow, so the interface loses its hierarchy.
• A state, essential control, or text label fails contrast because a light-theme value was reused.
• Meaning depends on hue alone, or content imagery has been inverted to fit the shell.

Responsive adaptation guidance

• Collapse command, run, telemetry, and status modules with @container queries while preserving their labels and surface order.
• Keep the luminance relationship between any surfaces that remain stacked; a narrow layout may have fewer levels, not arbitrary levels.
• Re-measure text and state contrast at increased type scale and 200% zoom.
• Move long technical values to a readable line or clipped, labelled region rather than shrinking body type.