Theme and dark mode

Dark mode always starts out well. You add dark:bg-slate-900 next to bg-white, dark:text-slate-100 next to text-slate-900, and the home screen looks convincing in ten minutes. Then comes everything else: forty components, each with its own backgrounds, borders, and hover states. Every color class calls for a second one. Your class attributes double in length, and a month later you find that three shades of dark border coexist, because nobody remembers which one was chosen.

The symptom is real, but the cause isn't dark mode: it's having written literal colors in your components. bg-white describes a pigment, not a role. As long as your components name pigments, every additional theme multiplies the classes. If they name roles instead — the surface of a card, the color of body text, the color of a subtle border — then switching themes means redefining a dozen values in a single place, and the components no longer contain a single dark: variant.

Defining your theme

All customization lives in the stylesheet, under @theme. Each declaration produces both a CSS variable and the corresponding utilities: