Dark theme and contrast

You already shipped this, twice

Put your phone in dark mode and open Pocket Notes. The page goes near-black, the text goes warm cream, the round + button changes from deep brown to bright amber. Nothing flashes, nothing is unreadable, and you wrote no if statements to make it happen.

That works because Theme.kt contains two complete colour schemes, not one scheme and a switch. This lesson is about why it has to be two, and about the number that tells you whether either of them is any good.

One theme, two schemes

Here is the real switch, at the bottom of Pocket Notes' theme file.

And the two schemes it chooses between, trimmed to the slots worth comparing:

1private val LightColors = lightColorScheme(
2    primary = Color(0xFF8A5100),
3    onPrimary = Color(0xFFFFFFFF),
4    surface = Color(0xFFFFFBF7),
5    onSurface = Color(0xFF211A13),
6    onSurfaceVariant = Color(0xFF514538),
7    surfaceContainer = Color(0xFFFDEDE2),
8    // ...and about thirty more
9)
10
11private val DarkColors = darkColorScheme(
12    primary = Color(0xFFFFB959),
13    onPrimary = Color(0xFF4A2800),
14    surface = Color(0xFF17110E),
15    onSurface = Color(0xFFEDE0D4),
16    onSurfaceVariant = Color(0xFFD5C3B4),
17    surfaceContainer = Color(0xFF241E1A),
18    // ...and about thirty more
19)

Look at primary. Light is #8A5100, a deep brown. Dark is #FFB959, a bright amber. Those are not inversions of each other — they are the same idea, honey, at two very different brightnesses, because the thing behind them changed completely.

The "on" rule

Notice that every colour has a partner. primary has onPrimary. surface has onSurface. That pairing is the most useful convention in Material 3, and it is not decorative: the "on" colour is the colour guaranteed to be readable when painted on top of its partner.

So the rule for writing a component is: pick the container colour, then use its partner for anything on top.

1FloatingActionButton(
2    onClick = onNewNote,
3    containerColor = colors.primary,
4    contentColor = colors.onPrimary
5)

In light mode that is white on deep brown. In dark mode it is dark brown on amber. One piece of code, two correct results, and you never had to think about either.

Why you do not type a colour where you use it

The rule people repeat is "never hardcode Color.White". It is nearly right, and the reason matters more than the rule.

Pocket Notes' light scheme literally contains onPrimary = Color(0xFFFFFFFF). Dice Duel's is even blunter — onPrimary = Color.White. Neither is a bug. They sit inside lightColorScheme(...), where "white" is a considered answer to "what goes on top of violet in daylight", and the dark scheme answers the same question separately with VioletInk.

The bug is typing a colour at the point of use:

1Text(
2    text = note.title,
3    color = Color(0xFF211A13)
4)

That is the light scheme's onSurface, frozen. In dark mode the surface behind it becomes #17110E and the text is near-black on near-black — a contrast ratio of 1.1:1, which is to say invisible. Nothing warns you. It builds, it runs, and it is unreadable for every user who prefers dark mode.

There is exactly one honest reason to hardcode, and Dice Duel has it:

1// A real die is white with dark pips, in any light.
2val DieFaceLight = Color(0xFFFDFBFF)
3val DiePipDark = Color(0xFF241A4D)

The die is a physical object with a real colour. Dice do not go dark at night. When your colour is a fact about the world rather than a choice about your UI, name it, comment why, and keep it out of both schemes.

Cards in the dark: tonal elevation

In daylight, a card floats above the page because of a shadow. On a near-black background a shadow is invisible — black on black.

Material 3's answer is tonal elevation: instead of a shadow, a raised surface gets a slightly lighter colour. That is what the surfaceContainer family is for. Pocket Notes' dark scheme, from the back of the screen forwards:

Those steps are tiny — the contrast between the page and a card on it is about 1.1:1. That is deliberate. You are not trying to make the card readable against the page; you are trying to make its edge findable. Push the steps further apart and a list of cards turns into a stripey mess.

The rule of thumb: surface for the page, surfaceContainerLow for things resting on it, and each step up as things move towards the front.

What a contrast ratio actually is

Every colour has a luminance — how much light it puts out, from 0 for black to 1 for white. A contrast ratio compares the luminance of two colours and produces a number between 1:1 (identical, invisible) and 21:1 (pure black on pure white).

The thresholds come from WCAG, level AA:

• 4.5:1 for normal body text.
• 3:1 for large text — roughly 18sp and up, or 14sp bold — and for the edges of controls like a switch track or a text field outline.

You cannot judge this by eye. Two colours that look obviously different can fail, and that is the whole reason the number exists. Here is how the real schemes score:

The sixth row is the point of this entire lesson. #8A5100 is a perfectly good accent colour — it scores 6.3:1 on the light page it was designed for. Move that exact colour onto the dark page without changing it and it drops to 2.9:1, below the threshold for body text, and someone reading in bed cannot make out your button.

The last row is the classic web mistake, sitting at the same score, which should tell you how easy it is to make.

The same screen, both ways

Every element is in the same place. Nothing moved, nothing resized. Only the forty values in the scheme changed — and the + flipped from white-on-brown to brown-on-amber, because onPrimary did its job.

The half-second before Compose draws

There is one moment your colour scheme cannot help with. Between the launcher starting your activity and Compose drawing its first frame, the window already exists and has to be painted something. If that something is white, a dark-mode user gets a white flash on every launch.

That is what the XML themes are for, and why every app has two of them:

1<style
2  name="Theme.PocketNotes"
3  parent="android:Theme.Material.Light.NoActionBar">
4  <item name="android:windowBackground">#FFFBF7</item>
5</style>

1<style
2  name="Theme.PocketNotes"
3  parent="android:Theme.Material.NoActionBar">
4  <item name="android:windowBackground">#17110E</item>
5</style>

Same style name, same theme the manifest points at. The only difference is the folder: values-night is a resource qualifier, and Android reads that folder instead whenever the phone is in dark mode. No code, no check, no if.

The two hex values are background from the light scheme and background from the dark scheme, copied by hand. They have to be typed twice because XML resources and Kotlin Color values live in two different worlds — which is exactly why the comment above them in the real file says what they are for.

Focus Flow does the same thing one step tidier: both its themes point at @color/window_background, and it is that colour which has a values-night version.