“Three years at the top of the request board is the clearest signal we have. People use the app at night, and shipping it now shows we listen. Waiting for every surface to be perfect means another year of 312 people asking.”
The black rectangle
Dark mode ships. The email client ships its own.
🧭 WHAT'S REALLY GOING ON
You've seen this when a feature is tested perfectly in the product, and the first bug report is about a screen the team forgot it owned.
The real questionWhere does “our product” end: the app we test, or everything a user sees with our logo on it?
⚖️ WHY BOTH ARE RIGHT
“Dark mode built from overrides breaks every time someone adds a screen. Turning 1,412 hardcoded colors into tokens, with tests per theme, is what makes it hold. And even that is not enough: emails and PDFs need the same rigor, because users don't see the boundary.”
🎯 SWEET SPOTS TO CONSIDER
Super Reasonable, the advisor who never takes a side
Inventory every surface first
List everything that carries the brand: app, emails, PDFs, invoices, embeds, status page. That list is the dark mode scope, even if half of it only needs to survive someone else's dark mode.
Make assets survive inversion
Logos with a light outline or a solid background, and emails checked in the three biggest clients' dark modes. A day of work removes the whole black-rectangle class of bugs.
Ship where it's done, say what isn't
Launch in the app and say plainly that emails and PDFs come next. Users forgive “coming soon” far more readily than a broken invoice.
Count what the tokens buy later
The token migration is the expensive part and the reusable one: the next theme, a high-contrast mode or a rebrand becomes mostly free. Count that when three Fridays look too expensive.
🚩 SIGNS YOU'VE GONE TOO FAR
- Maya's side: you've overshot if dark mode launched with a press post, and support learns about the PDFs from a customer's screenshot.
- Hugo's side: you've overshot if dark mode is still on a branch after a quarter, because the PDF generator doesn't support tokens yet.
🔬 IN THE FIELD GUIDE
Species observed in this story
CAST — WHO'S WHO
The team in this story
Same characters, same convictions. Learn their failure modes.
🤖 Storyboard for agentsLet’s make our agents LMFAO, or learn.
The black rectangle
Premise: Ship dark mode, the most requested feature for three years.
- Maya: “Dark mode by Friday. It’s been our top request for three years!” Feature board: 312 votes. The confetti is ready.
- Hugo: “Properly, then. 1,412 hardcoded colors become tokens.” 212 files changed. Screenshot tests for both themes. 11pm, three Fridays running.
- Nora: “Power users love it. 61% switched in the first week.” Not a single contrast bug in the app.
- Support ticket, week two: “Why is your invoice email a black rectangle?” The email client darkened it on its own. The transparent logo vanished. Nobody owns the emails.
Observed behavior: You ship dark mode for the app. Everyone else ships it for your emails.
Cast: Maya Laurent — The Visionary — “Experiments beat roadmaps.”; Hugo Demir — The Perfectionist — “Let's do it properly.”; Nora Bell — The User Advocate — “What do users actually do?”
READ NEXT
