Theming Beyond a Color Swap

The plain-language idea

The naive version of dark mode is "swap light backgrounds for dark ones and dark text for light text" — and it's exactly the naive version that produces a theme that ships with real, visible bugs. Real theming is the semantic token layer from the design-tokens lesson, doing its actual job: components reference roles (--color-bg, --color-surface, --color-text, --color-border), and the theme decides what value each role resolves to. A component built correctly never says "make this dark" — it says "use the background role," and the active theme decides what that currently means.

Two things break specifically in dark mode that don't in light mode, which is why "invert the colors" undersells the actual work:

• Elevation stops reading as shadows. In light mode, a raised card gets a dark, soft shadow against a light background — that reads clearly as "above" the page. On a dark background, a dark shadow has almost nothing to contrast against, so the same technique visually disappears. Dark-mode elevation is conventionally communicated with a lighter surface fill instead — a card that's a shade lighter than the page background, not a shadow underneath it.
• Images and brand colors don't automatically survive a theme flip. A logo or illustration designed with dark line-work on a transparent background vanishes against a dark page; a brand accent color tuned for contrast against white can fail contrast against near-black. These need theme-specific variants, not a blanket filter or opacity trick over the light-mode asset.

See it in a real thing: three roles, two themes

This platform's own token system (from the design-tokens lesson) is a real instance of this: --color-bg, --color-surface, --color-surface-raised, and --color-fg are semantic roles, and the light and dark theme definitions each supply their own independently-tuned values for every one of them — not a single value run through an automatic inversion filter.

:root {
  --color-bg: var(--p-neutral-50);
  --color-surface-raised: var(--p-neutral-0); /* lighter than bg → elevation via shadow works */
}

:root[data-theme="dark"] {
  --color-bg: var(--p-neutral-950);
  --color-surface-raised: var(--p-neutral-850); /* lighter than bg, not darker — elevation via fill, not shadow */
}

What people usually miss

Watch out

• A CSS filter-based "invert" (filter: invert(1)) is not real dark theming. It technically flips lightness, but it also inverts hues, breaks images and icons that were never meant to be inverted, and gives no way to independently tune any one role — it's the "swap colors" anti-pattern automated, not solved.
• Elevation needs a different technique in dark mode, not just a re-tinted shadow. A dark shadow on a dark background barely registers — lighter-surface-fill is the standard fix, and skipping it is why raised cards in a dark theme often look flat even when every color is nominally "dark mode compliant."
• A value tuned for one theme is never safe to assume for the other. This isn't a hypothetical — it's a documented failure mode on this exact platform, where feedback colors and accents shipped with only one theme's contrast verified and silently failed AA in the other.
• Brand and image assets are a real, separate cost of supporting dark mode, not an edge case — a logo, illustration, or photo with a fixed light background needs a considered dark-mode treatment (a transparent or alternate version), not a filter slapped over the original.

Why this matters in interviews

"How would you implement dark mode?" separates a candidate who says "swap the CSS variables" (true but incomplete) from one who names elevation and asset handling as the parts that actually take real design work — and can explain why a shadow-based elevation technique specifically breaks on a dark background instead of just asserting that it does.