Theming and dark mode, done right

Users expect dark mode, and bolting it on as a duplicate stylesheet is how teams end up maintaining two sources of truth that slowly drift apart. The maintainable path is semantic tokens.

Instead of naming a color 'gray-900', name it by role: 'surface', 'text-strong', 'border'. Each theme maps those roles to concrete values, and every component references the role. Switching themes becomes swapping a small map, not rewriting components.

The subtleties are in the details. Dark mode is not just inverted — shadows barely read, so elevation shifts to subtle borders and lighter surfaces; pure white text on pure black vibrates, so both are pulled toward gray. These are design decisions, not toggles.

Get the token layer right and a full rebrand — or a new client's palette — becomes an afternoon, not a quarter.