Dark Mode: Build a Dark Theme From the Same Shared Color Roles
Learn why dark mode is a separate theme rather than flipped colors, and how mapping named roles to dark values keeps screens readable and on-brand.
In short
Dark mode is a separate theme, not flipped colors, built by mapping the same named color roles to dark values so screens stay readable and on-brand.
13 min readFree
What You Will Learn
Dark Mode is a second color theme for a design system. It swaps the light backgrounds for dark ones, but it keeps text easy to read and keeps the brand easy to spot. Many products now offer both a light and a dark look, so designers need a clear method for building the dark one.
In this lesson you will learn why a good dark theme is not a simple flip of colors, how to build one by mapping named roles to a second set of values, and how to check the result on real screens. You will also walk through one example from start to finish.
Key words
- Theme
- A full set of color choices that a product uses on every screen. A light theme and a dark theme are two themes of the same product.
- Dark Mode
- A dark theme that uses mostly dark surfaces, with light text and a few color accents.
- Inversion
- Flipping every color to its opposite, so light becomes dark and dark becomes light. This is a quick trick, and it usually does not work well.
- Surface
- A background plane that a piece of the screen sits on, such as the page, a card, or a pop-up box.
- Role (semantic name)
- A name that says what a color is for, such as surface or text-primary. It does not say what the color looks like.
- Desaturate
- To make a color less vivid and less strong, so it looks softer.
- Contrast ratio
- A number that shows how far apart two colors are in lightness. Higher numbers mean text is easier to read. It is written like 4.5:1.
- Elevation
- How high a surface seems to sit above the page. A card that floats above the page has more elevation than the page does.
- Overlay
- A thin, see-through layer of color placed on top of a surface to lighten or tint it.
Is Dark Mode a Separate Theme, Not an Inversion?
The fastest way to make a dark screen is to invert it. Every light color flips to a dark one, and every dark color flips to a light one. The result often feels wrong. One design writer argues that a dark interface needs its own tuned palette and its own depth rules, which means it is closer to a second design than to a copy. A good dark interface needs a tuned palette, contrast that meets accessibility targets, and depth shown with light surfaces rather than shadows.
Three problems show up again and again when a team simply flips colors.
Bright colors buzz
A vivid color that looks fine on white can seem to vibrate against a dark background. Designers sometimes call this effect chromatic aberration. It tires the eye.
Shadows disappear
On light screens, shadows show that a card is above the page. On a dark background, shadows are hard to see, so the same approach does not work.
Black feels harsh
A flipped screen often lands on pure black, which looks stark. Dark gray is the safer base, as covered in the next part of this lesson.
The rest of this lesson gives the three main rules that replace a simple flip: use dark gray, soften the brand colors, and show depth with lighter surfaces.
Why Use Dark Gray, Not Black?
Google's Material Design system uses dark gray as the main surface color for components. The recommended dark theme surface color is #121212. The reason is comfort. Light text on dark grey has less contrast than light text on a black surface, and that lower contrast reduces eye strain.
Black still has one job. Material Design reserves true black for saving battery on OLED screens. For most screens, a dark gray base is the better choice.
Why Soften the Brand Colors?
A bright brand blue that looks confident on white can look harsh on dark gray. The usual fix is to desaturate it. Designers desaturate primary colors so that the contrast against the dark surface is enough. Material's baseline dark theme goes further and uses the 200 tone of the primary palette, saving full saturation for one or two elements.
Not every hue needs the same change. Treat each brand color as its own test case.
Tip
Soften the color, but keep its hue. Your goal is to keep the brand recognizable. One guide says the aim is to preserve brand recognition while respecting the visual physics of a dark surface.
How Do You Show Depth With Lighter Surfaces?
On a light screen, a higher card gets a bigger shadow. On a dark screen, the same card gets a lighter surface. Default themes use shadows to show elevation, while a dark theme also shows elevation by adjusting the surface color. Material's rule is simple: as a surface rises in elevation, it becomes lighter in color.
In practice, a dark theme builds the lighter surface with a thin overlay. A dark theme surface is built by placing a semi-transparent overlay over a component surface. One summary of Material's scale places this overlay at 5 percent at the lowest elevation and 16 percent at the highest level, rather than relying on shadow contrast alone.
Keep the depth rule consistent. A simple test is whether a higher surface is lighter than the surface under it. Stacking a dark card on a darker page works, but a light card on a dark page can look like a hole.
How Do You Build the Dark Theme by Mapping Roles to Values?
The main build method is mapping. Instead of picking a color for each screen, the team gives each color a role name based on its job. Each role then gets two values, one for the light theme and one for the dark theme. Components only use the role names. This is why one button can work in both themes without anyone drawing it again.
The idea is simple, but it takes care. A design system holds the roles, and the screens just reference them. Dark mode in a design system is a second set of values for the same semantic color tokens, so each component changes theme without being redrawn. The next parts explain how to name roles and how to map a light screen step by step.
Name Colors by Their Job
A good role name says what the color does. Material 3 also moved away from elevation numbers. Tone-based surface color roles have replaced the older approach of surfaces at +1 to +5 elevation.
Surface roles
Names for background planes, such as the page, a card, or a pop-up. One approach uses five surface tokens that cover most products: page, container, raised, overlay, and inverse.
Text roles
Names for the main text, secondary text, and text on a colored button. Components reference roles like text, and each role holds a light and a dark value.
Border and accent roles
Names for thin lines, focus rings, and brand highlights. Each one gets its own dark value, so it still stands out on the dark surface.
Names should describe purpose, not appearance. A name like surface-container-high survives a redesign, while a name like elevation-3-dark does not.
Keep Components Unchanged
A button, card, or input should only point to roles. It should not carry its own color values. Dark mode works best as a mode of semantic color tokens, so components reference roles and never hex values. A hex value is a color written as a # sign followed by six characters, such as #121212. When the theme changes, the role changes its value, and every component that uses that role follows.
This is also why a team should avoid a hidden trick: skip invert filters, which wreck photos and brand colors.
What Are the Steps to Map a Light Screen?
- 1
List every color on the light screen
Include the page background, cards, text, buttons, borders, icons, and state colors such as error or success.
- 2
Give each color a role name
Name it by its job, such as page surface, card surface, primary text, or primary button. Avoid names that describe the look, such as light blue.
- 3
Assign a dark value to each role
Use dark gray for surfaces, a slightly softer white for main text, and a softened tone for the brand. Keep each dark value in the same color family as its light partner.
- 4
Check each pairing
Test text on its surface, a button label on its button, and each border on its surface. Fix the role value that fails, not the component that uses it.
- 5
Review states and special cases
Check hover, pressed, disabled, and error states. Decide where a role should stay light on purpose, such as a snackbar that must stand out.
A good starting point is a small set of roles. Map the most common ones first, then add more when a real screen needs them. When a team builds a dark palette from the light one, the mapping can end up almost one to one.
Tip
Make a one-page table with three columns: role name, light value, dark value. Share it with the team. It becomes the easiest way to spot a missing role.
Worked Example: A Light Card Becomes a Dark Card
This walk-through uses Google's Material Design dark theme rules on one common screen part: a light card with a primary button. It shows how the idea works. It is not a copy of a shipped app screen, so check the real product before you copy exact values.
- 1
Start with the light version
The page is near white. The card is white with a soft shadow. The text is dark gray. The button is a bright brand blue with a white label.
- 2
Map each part to a role
The page becomes the page surface role. The card becomes the raised surface role. The text becomes the primary text role. The button becomes the primary action role. The shadow is removed from the list of roles and replaced by a depth rule.
- 3
Change the page to dark gray
The page role gets a dark gray value instead of white. A dark theme uses dark grey, rather than black, as the primary surface color for components. The starting value is #121212.
- 4
Lift the card with a lighter surface
The card gets a slightly lighter surface than the page. It is built with a thin white overlay, so the card looks raised without any shadow. Keep the overlay low, so the card stays calm.
- 5
Remove the shadow and rely on the lighter surface
On this dark page, the shadow would be almost invisible. The lighter card carries the sense of depth alone. Default themes use shadows to express elevation, while a dark theme also expresses elevation by adjusting the surface color.
- 6
Soften the blue button
The saturated blue becomes a lighter, muted blue from the same hue family. This stops it from glowing against the dark card. It still reads as the brand blue, so the product stays recognizable.
- 7
Keep the text readable
The main text becomes a light, slightly soft white rather than pure white. For pure white, maximum contrast against dark backgrounds can cause halo effects around letters, so designers often choose a slightly darker white. Check that body text on the lightest card still reaches at least 4.5:1 contrast.
- 8
Check the button label too
The label on the softened blue must also pass the contrast check. If it fails, change the label role or the button role, not each button one at a time.
The result keeps the same parts, the same layout, and the same brand. Only the role values changed, so every other screen that uses these roles gets the same update.
Check Contrast and Test Real Screens
A dark theme can look fine at a glance and still fail in use. Test both themes, every important role pair, and real screens. For normal text, the common target is 4.5:1, and large text can use 3:1. This lesson covers only the basic check. Full accessibility rules are in their own lesson.
Measure Contrast in Both Themes
Dark surfaces need extra care because the lighter raised surfaces are the hardest to read on. Material Design recommends #121212 and asks that white text on the base surface reach at least 15.8:1 contrast, so body text still passes 4.5:1 on the lightest raised surface.
Test at every elevation level, not only the base. Body text should be tested on the highest, lightest surface. WCAG is the accessibility standard that sets these numbers.
Secondary colors need checking too. In a dark theme, a saturated secondary color can fail the 4.5:1 contrast level against dark surfaces.
Test States, Borders, Images, and Icons
Many dark theme bugs hide in the small parts. Walk through each part on real screens and look for these problems.
States
Check hover, pressed, focus, disabled, and error. Error red can be too loud on dark gray.
Borders
A thin line can vanish on dark gray or glare on black. Check that UI components and meaningful graphics need 3:1 against adjacent colors.
Glare and halos
Bright elements on a dark screen can bloom and glow. The first step in a dark theme is to stop using bright, colorful surfaces. Look for large bright areas that pull the eye away from the content.
Images and icons
Icons need the same contrast check as text. Photos and brand artwork should not be flipped to fit the dark theme. Choose a version or a background that suits them.
Test on the screens people really use. One guide warns that browser simulations of dark mode can be unreliable, so the team should test on real screens.
Tip
Look at each dark screen in a dim room and in bright light. Glare and halos often show up in only one of these settings, so one test is not enough.
Check Your Understanding
Try these two scenarios. Each one needs the ideas from this lesson to answer.
Quick check
A teammate makes a dark theme by inverting every color on a light screen. The bright blue primary button now looks harsh against the background, and the card shadows have vanished. Which two changes would fix it best?
Quick check
A dark settings page uses a dark gray card on a dark gray page. Designers say the card blends into the background, and the gray helper text under each setting is hard to read. The team uses semantic roles such as page surface, raised surface, and secondary text. What is the best next step?
Sources
- Material Design: Dark theme guidelines
- Material Design 3: Color overview
- Material Design: Building a Material Dark Theme on Android
- Pegasus Design System: Building a dark mode design system
- UX Design Institute: Dark Mode Design, a practical guide
- Robosoftworks: Designing for Dark Mode, best practices
- ColorArchive: Dark Mode Color Design, building a system not an inversion
- Tenet UI (Design System Chronicles): Scalable and Accessible Dark Theme
- Made Good Designs: Dark Mode Design, Best Practices
- Antikode: Dark Mode UI Design, Best Practices and Common Pitfalls
- UX Planet: 8 Tips for Dark Theme Design
- UXKB by fuguUX: Dark theme (Material Design) summary
- Natebal: Best Practices for Dark Mode in Web Design
Last updated on 17 November 2026
Related lessons
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.