Dark Mode Is a Second Design, Not a Filter

The theme that looks almost right

The quickest way to ship dark mode is to swap white for black and black for white. It works, in the sense that text stays readable. It also looks slightly off in a way that is hard to name: shadows vanish, the accent color glares, and every border seems either too loud or missing.

That is because a dark theme is not the light theme with the lights off. Colors behave differently on a dark background, and a few of them need their own decisions.

Name colors by job, not by shade

The fix that does most of the work is a vocabulary change. Instead of components using white, gray-100, or #1b222d, they use names that describe a job: background, card, surface, border, muted-foreground. Each theme then decides what those jobs look like.

In practice, this means a component written once never needs a dark: variant for its colors. When the theme changes, every surface changes with it.

Three things tokens don't solve

That sounds like the whole job, but a few details still need a human eye:

Two designs, one vocabulary

The point is not that dark mode is twice the work. With semantic tokens, most of it really is automatic. It is that the remaining part, the accents, the depth, the imagery, deserves the same attention as the light theme. People who choose dark mode often use it all day, and they notice when it was an afterthought.