Multi-theme infrastructure for a component library

WHAT THIS TESTS This is a systems-design question about theming: can you separate component styling from theme values and choose a sound runtime switching mechanism.

A GOOD ANSWER COVERS The foundation is indirection through semantic tokens. Components never reference raw colors; they style against semantic CSS custom properties like --color-surface, --color-text, and --color-action. Each theme or brand is a set of values for those same properties. Define them under a scope, commonly an attribute or class on a root element, for example a default set on :root, an overriding set under [data-theme=dark], and additional sets per brand. Because every component reads var(--color-...), switching the attribute at runtime instantly retheme the whole tree with no rebuild and no per-theme bundle. Layer this over a token pipeline so core primitives map to semantic tokens per theme.

COMMON WRONG ANSWERS Hardcoding hex values in components, which makes theming impossible without editing each component. Building a separate CSS bundle per theme and shipping the right one, which is heavier and cannot switch at runtime. Relying solely on JavaScript to set inline styles, which is brittle and hurts performance versus cascading custom properties.

LIKELY FOLLOW-UPS How do you avoid a flash of the wrong theme on first paint? Set the theme attribute server-side or in a tiny inline script before render, often reading a cookie or prefers-color-scheme. How do you honor system preference? Default via the prefers-color-scheme media query while letting an explicit choice override it. How do brands differ from light/dark? Same mechanism with more token sets, possibly composed as brand plus mode. Where do tokens come from? A Style Dictionary pipeline emitting per-theme custom property blocks.

ONE CONCRETE EXAMPLE :root defines --color-surface #ffffff and --color-text #111111; [data-theme=dark] redefines them to #111111 and #ffffff. A Card uses background: var(--color-surface); color: var(--color-text). Setting document.documentElement.dataset.theme to dark flips every card, button, and surface at once with no component change and no new download, and an inline script that reads the saved preference before first paint prevents a light-to-dark flash, demonstrating a runtime-switchable, single-bundle theming architecture.