Dark Mode

It’s 11 p.m. A customer opens their banking app in bed to check a payment. The phone is in dark mode, the app is in dark mode… except for one card in the middle of the screen, where the “Pending: €1,250” text is black on dark grey. The customer can’t read it, assumes the money is gone, and calls support in a panic.

Nothing “crashed”. No test case failed. The app simply was never checked with the lights off. dark modeDark modeA display setting that uses light text on dark backgrounds.Open in glossary → looks like a cosmetic setting, but a lot of people keep it on all day, and it touches every screen, every color and every image in your product. That makes it one of the easiest places for a new tester to find real, visible bugs.

How it works

A theme is just a set of colors. Light mode uses dark text on light backgrounds, dark mode flips that. The interesting part for testers is who decides which theme the user gets, and when it changes.

Who wins: system or app?

Phone setting	In-app setting	The user should see
Light	System	Light
Dark	System	Dark
Dark	Light	Light (the app overrides the phone)
Light	Dark	Dark

That’s four combinations already, and each one should survive a restart, a theme change while the app is open, and a fresh install. Try them in the lab below.

Switching while the app is open

This is where the platform differences show up:

• Android treats a dark theme change as a configuration changeConfiguration changeAn Android event like rotation, folding, dark mode, font size or language that recreates the screen by default.Open in glossary →, just like rotating the phone. By default, the visible screen is destroyed and recreated. If the app doesn’t save its state, a half-written review or a scroll position disappears the moment the theme flips. It’s the same family of bugs as in Orientation and screen sizes.
• iOS keeps the screen alive and sends a trait change (the “user interface style” trait goes from light to dark). Semantic colors update automatically, but anything the developer drew once and cached (a custom chart, a generated image, a color stored in a variable) can stay in the old theme until you leave the screen.
• Web: the page doesn’t reload. CSS using prefers-color-scheme updates live. Colors set by JavaScript only update if the code listens for the change.

Try it: the theme lab

Flip the phone’s appearance, the in-app setting and Increase contrast. The badge shows which theme the user actually gets. Then pick an element and measure its contrast ratioContrast ratioHow different text and background colors are; WCAG asks for at least 4.5:1 for normal text.Open in glossary → in both themes. The sample screen has a few realistic flaws in its default colors. Can you find which elements fail, and in which theme?

Phone appearance

LightDark

In-app setting

SystemLightDark

Accessibility

Increase contrast

The user sees the light theme. The in-app setting is "System", so the app follows the phone: light.

9:41

Wallet

Updated 2 min ago

Balance

€2,480.15

Search payments

RecentSee all

Send money

9:41

Wallet

Updated 2 min ago

Balance

€2,480.15

Search payments

RecentSee all

Send money

Contrast checker

Balance textCaptionSee all linkButton labelField border

light #6b7280 onon #ffffff4.83:1 Pass

dark #6b7280 onon #0000004.34:1 Fail

Text: WCAG AA needs at least 4.5:1 for normal-size text. The dashed outline shows the measured element.

Example requirements

Notice criteria 3 and 9: they’re about timing, not colors. Many teams test the “steady state” of each theme and never the moment of switching.

What usually goes wrong

#	Bug	What you see	Typical severity
1	Hard-coded colors	Black text on a dark card, or a white box on a black screen	High (text unreadable)
2	Images with baked-in colors	A black logo on a transparent PNG vanishes; an icon with a white rectangle behind it	Medium
3	Shadows instead of borders	Cards separated only by a shadow blend into the dark background	Low–Medium
4	Low-contrast greys	Captions, placeholders and disabled text pass in light, fail in dark	Medium–High
5	Selected state disappears	Selected tab, chip or day looks like all the others	High
6	Status bar icons	Black clock and battery on a black header	Medium
7	Web views and emails	Help pages, receipts, ads or HTML emails stay bright white	Medium
8	Charts	Gridlines, labels or a dark series line vanish	Medium
9	Brand colors	A dark navy button or link becomes unreadable on black	Medium
10	Third-party screens	Payment, login or chat SDK screens stay light or mix themes	Low–Medium
11	In-app setting not saved	“Light” is selected in Settings, but the app is dark after a restart	Medium
12	State lost on switch	Android: typed text or scroll position reset when the theme changes	High
13	Web flash of wrong theme	The page shows white for a moment before turning dark	Low–Medium

Don’t forget the places outside the app’s own screens: screenshots in the help center or app store listing (do you need dark versions?), push notification images, and widgets, which follow the system theme even when the app has its own setting.

Find the bug

PulseFit, a fitness app, just shipped dark mode. The app and its website below have six bugs. Explore like a tester:

• Switch the system appearance to Dark and look carefully at every part of the Today screen.
• Tap the Today / Week / Month chips in both themes.
• In Settings, choose Light or Dark, then Restart app.
• Open the Website in dark mode and reload it. Watch closely.

🐞 Bug hunt: PulseFit dark mode

This demo has 6 hidden bugs. Explore it like a tester, then check your findings.

Found0/6

9:41

MK

Good morning, Mia

Tuesday, 14 October

todayweekmonth

6,240

Steps

410

kcal

38 min

Active

Weekly summary

You were active 5 of 7 days. Two more workouts and you hit your monthly goal!

Sponsored

FuelBox

Protein bars, 20% off

Code PULSE20 at checkout. Ends Sunday.

Shop now

Device

Restart app

System appearance (Control Center / Quick Settings)

Light Dark

Open

App Website

From the spec

The app and website support light and dark themes. By default they follow the system. In the app, Settings › Appearance can force Light or Dark, and the choice is remembered.

1. 1

   Hint: Switch the system to Dark and read every card on the Today screen.

   Weekly summary text is invisible in dark mode

   The card background follows the theme (#1C1C1E), but the body text is hard-coded to #1A1A1A. Contrast is barely above 1:1, so the text is practically invisible. Expected: a semantic text color that passes 4.5:1 in both themes.

   Reveal answer✓ I found this
2. 2

   Hint: Look at the top-left corner in dark mode.

   Logo wordmark vanishes on the dark header

   The logo is a near-black wordmark on a transparent background. In dark mode only the pink pulse icon is visible. Expected: a light version of the logo (or a semantic fill) in dark mode. Notice the splash screen and the website already do this right.

   Reveal answer✓ I found this
3. 3

   Hint: Tap Today, Week and Month with the system set to Dark.

   Selected chip looks the same as the others in dark mode

   In light mode the selected chip is black with white text. In dark mode all three chips use the same grey background and white text. Only the numbers change, so the user cannot tell which range they are looking at. Expected: a clear selected style (fill, border or checkmark) in both themes, not just a slightly bolder font.

   Reveal answer✓ I found this
4. 4

   Hint: Scroll to the Sponsored block in dark mode.

   Sponsored web view stays bright white

   The partner offer is embedded web content with no dark styles, so a glaring white box sits in the middle of a black screen. Expected: the web content supports prefers-color-scheme (or the app passes the theme to it), or at least uses a dark-friendly surface.

   Reveal answer✓ I found this
5. 5

   Hint: In Settings choose Light while the system is Dark, then tap Restart app.

   In-app Light or Dark setting is ignored after a restart

   The choice applies immediately and is saved (Settings still shows the checkmark on Light), but on a cold start the app follows the system again and opens dark. The saved preference is never read on launch. Expected: the app starts in the theme the user chose.

   Reveal answer✓ I found this
6. 6

   Hint: Open the Website with the system set to Dark, then tap Reload page.

   Website flashes white before turning dark

   The dark theme is applied by a script after the page has rendered, so each load shows the light page for a moment. On a dark phone at night this is a bright flash. Expected: the theme is set before first paint, for example with a CSS prefers-color-scheme media query and a tiny inline script in the <head> for a saved user choice.

   Reveal answer✓ I found this

Test scenarios

Functional

• With the in-app setting on System, switch the phone between Light and Dark: the app follows.
• Choose Light and Dark in the app’s settings: the change applies immediately, on every screen, including ones further back in the navigation stack.
• Close, restart and update the app: the in-app choice is remembered (this is state persistenceState persistenceWhether the app remembers what the user did after navigating away, rotating, or restarting.Open in glossary →).
• Automatic mode: set a schedule a minute ahead and wait for the switch while the app is open.
• The website follows the system theme and, if it has its own toggle, remembers the choice after a reload.

Switching at the worst moment

• Change the theme while typing in a form, with a modal or bottom sheet open, mid-scroll in a long list, and during a video or animation.
• On Android, check that nothing is lost: the theme switch is a configuration changeConfiguration changeAn Android event like rotation, folding, dark mode, font size or language that recreates the screen by default.Open in glossary →, so typed text, selections and scroll position must survive.
• On iOS, check custom drawings: charts, maps, generated images and gradients update without leaving the screen.
• Switch the theme while the app is in the background, then return to it.

Visual and contrast

• Walk through every screen in both themes, including empty, loading, error and disabled states. Use the Accessibility basics contrast rules: 4.5:1 for text, 3:1 for icons, borders and focus rings.
• Selected tabs, chips, toggles, radio buttons and calendar days are clearly different from unselected ones (compare with the segmented control page).
• Logos, illustrations, avatars and product photos: nothing vanishes, nothing sits in a white box.
• Cards and sheets are still separated from the background (shadows barely show on black).
• Charts: lines, labels, gridlines and legends are readable.
• Status bar and Android navigation bar icons are readable on every screen.

Embedded and external content

• Web views (help, terms, offers), in-app emails and receipts, rich push notifications and home screen widgets.
• Third-party screens: payment sheets, social login, chat support, maps, ads. Write down which ones you can’t change, and report them anyway so the team can decide.
• Screenshots and images in the help center and store listing.

Accessibility

• Turn on Increase Contrast (iOS) or High contrast text (Android) together with dark mode.
• Combine dark mode with large text (Dynamic Type or font size): nothing overlaps or gets cut off.
• The focus ring on the web is visible on dark backgrounds.
• Information is never shown by color alone (a red/green status needs text or an icon too).

Example test cases

Mobile vs web

Mobile appWebsite

• Switch fast: iOS Control Center (long-press brightness › Dark Mode), Android Quick Settings tile Dark theme. You’ll switch dozens of times, so put the tile where you can reach it.
• Simulators and emulators: in the iOS Simulator use Features › Toggle Appearance (Shift+Cmd+A). From a terminal: xcrun simctl ui booted appearance dark. On Android: adb shell cmd uimode night yes (and no to go back). See Simulators and emulators.
• Android recreates the screen on a theme change, so it’s your best tool for finding lost-state bugs. Fill in forms, then switch.
• iOS Automatic mode switches at sunset. Developers rarely test the switch happening while the app is open.
• Status bar: if the app forces dark status bar content, the clock and battery become invisible on dark headers. Check every screen, especially full-screen images and video.
• Widgets and notifications follow the system theme, even if the app has its own setting.
• Third-party SDKs (payments, chat, maps) may not support dark mode, or may follow the system while your app is forced to Light. Mixed themes look broken to users.
• Compare platforms: on Android, check both a Pixel and a Samsung device. Manufacturer skins can add their own dark options (see iOS vs Android).

• Emulate without changing your OS: Chrome DevTools › More tools › Rendering › “Emulate CSS media feature prefers-color-scheme”. Firefox’s Inspector has light and dark simulation buttons. See DevTools for testers.
• Flash of the wrong theme: reload with the cache disabled and a throttled network. Pages that apply the theme with JavaScript after load, or read a saved choice from local storageLocal storageBrowser storage where websites keep data that survives closing the tab, like settings or a cart.Open in glossary → too late, flash white first.
• Native controls: scrollbars, checkboxes, date pickers and dropdowns can stay light on a dark page.
  Dev note

  That happens without the color-scheme CSS property (or meta tag).
• Site toggle vs system: if the site has its own Light/Dark/System switch, test all combinations, a reload, and a second tab.
• Emails in Gmail, Outlook and Apple Mail each darken HTML emails differently: logos with transparent backgrounds and dark text in images are common casualties.
• Cross-browser: check Chrome, Safari and Firefox, and phone browsers in dark mode (Cross-browser testing).
• Print a page from dark mode: it should print with a light background, not a page of black ink.

Checklist

Dark mode checklist

0 of 14 checked

Copy

• The app follows the system theme when the in-app setting is System
• In-app Light and Dark apply immediately and survive a restart and an update
• Switching the theme while the app is open updates every visible screen
• No typed text, selection or scroll position is lost when the theme changes (Android!)
• All text passes 4.5:1 contrast; icons, borders and focus rings pass 3:1, in both themes
• Selected, disabled and focused states are clear in both themes
• No hard-coded black text or white boxes on dark screens
• Logos and images have no vanishing transparent parts or baked-in white backgrounds
• Cards and sheets are separated from the background without relying on shadows
• Charts, maps and custom drawings are readable and update when the theme changes
• Status bar and navigation bar icons are readable on every screen
• Web views, emails, receipts and third-party screens match the theme
• Increase Contrast / High contrast text and large text work together with dark mode
• The website follows prefers-color-scheme without a white flash on load

Check your understanding

Quick quiz

0/5 answered · 0 correct

1. 1.The phone is set to Dark. In the app, Settings › Appearance is set to Light. What should the user see?

   ADark, the system always winsBLight, the in-app choice overrides the systemCWhatever the app used last timeDLight only on the Settings screen

2. 2.On Android, you switch to dark mode while writing a review and the text disappears. Why is this common?

   ADark mode deletes drafts to save batteryBA theme change is a configuration change that recreates the screenCThe keyboard is reset by the systemDIt only happens on emulators

3. 3.A grey caption has 4.8:1 contrast on white and 4.3:1 on black. Which statement is true?

   AIt passes, the light theme is what countsBIt fails WCAG AA in dark mode for normal textCIt passes, 3:1 is enough for textDContrast does not apply to captions

4. 4.The company logo disappears in dark mode, but the app looks fine otherwise. What is the most likely cause?

   AThe image failed to downloadBA dark logo on a transparent backgroundCThe screen brightness is too lowDThe logo is too small

5. 5.Which tool lets you test a website in dark mode without changing your computer settings?

   AThe Network tabBLighthouseCChrome DevTools Rendering: emulate prefers-color-schemeDPrivate browsing

Key takeaways

• Dark mode has two switches: the system setting and (often) an in-app System / Light / Dark setting. The in-app choice wins and must be remembered.
• Test the moment of switching, not just each theme: Android recreates the screen (a configuration change), iOS sends a trait change, the web updates through prefers-color-scheme.
• The classic bugs: hard-coded colors, vanishing transparent logos, low-contrast greys, invisible selected states, white web views, unreadable status bars and a white flash on websites.
• Measure contrast in both themes: 4.5:1 for text, 3:1 for icons, borders and focus rings.
• Don’t forget content you didn’t build: web views, emails, charts, widgets and third-party screens.