Last year I worked on a fairly large project that had seen devs come and go. When it was time to add dark mode, it took me a full week to wrap up the styles everywhere. On Zapspace, a pet project of mine for notes, tasks, and media, it took less than 20 minutes.

Same feature, wildly different effort. This post is about why, written as the short guide I wish I'd had earlier. It's aimed at beginners, but I think it holds up at any level.

Why the first project took a week

That project was brownfield, which means years of code written by different people with different habits. Colors were hardcoded all over the place, something like this:

<div class="bg-[#ffffff] text-[#1a1a1a] border-[#e5e7eb]"> <button class="bg-[#2563eb] hover:bg-[#1d4ed8]">Save</button> </div> 

It works, and it's fast in the moment. The problem is that every one of those values is a decision with no name. Months later nobody knows whether #1a1a1a and #1b1b1b are meant to be the same color, and when dark mode shows up, you have to find every single one, work out what it was for, and add a dark: variant next to it. Then you spend the rest of the week hunting for the ones you missed.

Name colors by what they're for

The way I think about it now is like labelling boxes when you move house. A box labelled "kitchen" still makes sense after you've rearranged the whole place. A box labelled "blue box" doesn't.

On Zapspace we made a rule early on: colors get named by their role, not their value. With Tailwind v4, you define them once in @theme:

@theme { --color-surface-primary: #ffffff; --color-surface-secondary: #f6f8fb; --color-surface-muted: #eef2f7; --color-text-primary: #0f172a; --color-text-muted: #64748b; --color-accent-action: #2563eb; --color-accent-action-hover: #1d4ed8; --color-status-success: #16a34a; --color-status-danger: #dc2626; --color-border-subtle: rgb(15 23 42 / 0.12); } 

Tailwind turns each of these into utility classes automatically, so the same component from earlier becomes:

<div class="bg-surface-primary text-text-primary border-border-subtle"> <button class="bg-accent-action hover:bg-accent-action-hover">Save</button> </div> 

There isn't a hex code in sight, and it reads like intent: this is a primary surface, this is an action button.

Dark mode becomes one block of CSS

Because every component points at a name instead of a raw value, dark mode is just a matter of giving those names new values:

.dark { --color-surface-primary: #07101c; --color-surface-secondary: #0b1524; --color-surface-muted: #151e2e; --color-text-primary: #e8eef7; --color-accent-action: #3b8aff; --color-accent-action-hover: #5c9fff; --color-status-success: #1bb872; --color-status-danger: #ef5a5a; --color-border-subtle: rgb(180 205 235 / 0.14); --color-text-muted: #9aa6b8; } 

Then you toggle the dark class on the <html> element:

function toggleDark() { const isDark = document.documentElement.classList.toggle('dark'); localStorage.setItem('theme', isDark ? 'dark' : 'light'); } 

That's it. No dark: prefixes sprinkled across components, and no file-by-file migration. Most of my 20 minutes went into picking dark colors that actually looked good, not into wiring anything up.

I should be honest though: those 20 minutes didn't come from nowhere. They came from enforcing the rule from the start. If one developer slips in a bg-[#fff], that one element stays bright white on a dark page, and you're back to hunting.

Rules I follow now

  1. Name by role, not appearance. surface-primary survives a redesign. light-gray doesn't.
  2. No arbitrary color values in components. If you need a new color, add a token. This is the one I'd enforce in code review.
  3. Keep the palette small. Surfaces, text, accent, status, and border covered almost everything for me.
  4. Do it from day one. Retrofitting is the expensive part. Naming things properly at the start costs almost nothing.

Key takeaways

  • Dark mode isn't the hard part. Unnamed colors are.
  • Describe what a color is for, not what it looks like.
  • Define the names once in @theme, then override them in .dark.
  • Enforce the "no arbitrary colors" rule early, because that's what turns a week into 20 minutes.

Give your colors a name

Next time you're about to type bg-[#...], stop and ask what that color is actually for, then give it a name. It's a small habit that costs you a few seconds now and saves you a very long week later.

Note

This article is written for Tailwind v4, where design tokens are defined in CSS with @theme. If you're still on Tailwind v3, the idea is exactly the same, but the setup lives in tailwind.config.js instead. You'd point your color names at CSS variables under theme.extend.colors, and the .dark block stays as it is. The v3 docs cover this here: Customizing Colors (Tailwind v3).