Dark mode as a system decision

A dark mode design system is a second set of color decisions, planned with the light theme. It uses the same names. Paper, surface, ink, line, and accent each get a dark value chosen on purpose. Inverting the finished page is a filter. Filters flip shadows, crush photographs, and turn a careful accent into a color that glows and fails to read.

Decide both themes while the list of colors is still short. A team that adds dark mode the week before launch is really choosing twenty colors under a deadline, and then calling the result a theme. The work is smaller if those pairs exist from the first serious palette.

Why a filter fails

Inversion assumes color is a mathematical opposite. Interface color is a set of roles. The page is quiet. The text is strong. The line is barely there. The accent is the action. Those roles do not survive a flip. A hairline that was a slightly darker gray on white becomes a slightly lighter gray on black, often brighter than you wanted, and the page looks outlined in neon. A soft shadow, meant to lift a card, becomes a pale glow that looks like a bug.

Photographs and illustrations break first. A product shot prepared on white, inverted, turns into a negative. Logos with a dark wordmark disappear into the new background. You will end up protecting half the page from the filter, which means you no longer have a filter. You have a list of exceptions. That list is a theme, designed badly, under a different name.

Brand accents fail more quietly. An orange that looks sharp on white can vibrate on a near-black surface, or drop so much contrast that the button label fails. You find out in production, on the screen where the button sits on a raised card, which is a different dark than the page. A filter never saw that pair. You have to pick it.

The pairs you decide up front

Give every color token two values and one meaning. The meaning stays stable, which is what lets components stay ignorant of the theme. A button asks for accent and for the text color that sits on accent. It does not ask for a hex. The theme answers.

Start with surfaces. A dark theme usually needs at least two, sometimes three: the page, a raised card, and an overlay such as a menu. They have to be distinguishable without a heavy shadow. If your only tool for separation is a drop shadow copied from the light theme, the dark theme will look muddy. Separation can be a lighter surface, a quieter line, or both. Pick one approach and use it everywhere.

Then text. Primary text should be light enough to read and dull enough that it does not bloom. Pure white on pure black is harsher than people expect for long reading. A slightly softened ink on a slightly lifted paper is calmer and still clearly a dark theme. Muted text has to stay muted and still readable. This is where teams cheat, and where the theme starts to fail for anyone in imperfect light.

The W3C's Web Content Accessibility Guidelines organize accessibility around four principles, the first of which is that content is perceivable. Both themes owe that principle the same debt. Check ink on paper, muted ink on the card, and the button label on accent, in each theme. A pair that only works in the light theme is an unfinished token. Fix the value. Do not add a one-off color on the screen where you noticed the problem.

Lines and focus come next. A focus ring that was a dark outline on white may vanish on a dark card. Draw the ring as its own token. It can share the accent, or it can be a dedicated color if the accent is too close to a surface. Keyboard users find out immediately when this token was an afterthought.

What stays the same

Type does not change with the theme. If the dark theme seems to need a heavier weight, the light theme was probably too light, or the dark ink is too dim. Fix the color before you fork the type scale. Two type scales means two products that will drift the first time someone updates a heading.

Space, radius, and component structure stay put. A card has the same padding. A field has the same label position. Icons use the current text color rather than a baked-in fill, so they follow ink without a second icon set. Illustration is the exception you plan: some drawings need a dark variant, the way a logo needs a version that works on a dark ground. That is an asset decision, named in the system, not a CSS filter on the way out.

Motion stays as it was. A theme switch can be instant. A long cross-fade between palettes is decoration, and it should respect a person's reduced-motion setting the way any other large move does. The theme itself is not the motion.

When to skip dark mode

Skip it when the light palette is still moving every week. You would be maintaining two unsettled systems, and both would look accidental. Skip it when your screens are mostly photography on a white field, and you do not have dark versions of the pictures. A clothing shop, for example, often has a point of view that is the paper color. Forcing a dark theme onto that catalog can fight the brand harder than it helps the night reader.

Ship it when people live in the product for hours, or when they open it in dim rooms, and when you can name an owner for the pairs. A trading screen, a dashboard left open beside other work, a writing tool: these are fair candidates. Trade Moai, a public Hanabi interface concept organized around scanning, is the kind of surface where a dark theme can be the primary one, designed first, with light as the second set. The order can flip. The rule cannot. The second set is designed, not generated.

Also skip a third theme. High contrast, if you need it, is a set of stronger pairs for people who ask for it, and it deserves its own pass. It is not "even darker." Piling themes on is how a small team ends up with colors nobody can name.

How to keep the pairs honest

Review a screen in both themes before you call it done. The cheap version of this is a toggle in the design file and a class on the document in the browser. Look at empty states, errors, and disabled controls. Those are where a missing pair shows up as pure black text on a dark card, which means a value fell through to the browser default.

In code, the fall-through should be obvious. Tokens resolve to the active theme. A raw hex in a component ignores the theme and becomes a light-theme stain on the dark page. Treat that hex as a bug, the same way you would treat a missing label. Hanabi's interface work uses Tailwind and CSS variables for this reason: the component asks for a name, and the theme provides the value.

The names themselves are the subject of the companion piece, tokens, type, and the decisions that stop visual drift. Read it if the light theme is already full of one-off values. Dark mode will copy every one of them.

If you want both themes designed as pairs and built with the product, see Hanabi's services. The studio would rather plan the second set while the first set is still small enough to hold in one list.