The Semantic Token Layer Makes Theming Free

Because components consume only semantic tokens (see Three-Tier Design Tokens) and never raw values, a theme is just a block that re-points those semantic tokens:

[data-theme="dark"] {
  --color-bg:   var(--color-gray-950);
  --color-text: var(--color-gray-50);
  /* ...override semantics only, never primitives */
}

Dark mode, brand variants, and high-contrast themes all become a single override block — zero per-component changes. The indirection layer is what buys this: every component already asks for "background" not "white", so swapping what "background" means re-themes the whole app at once.

Corollary — the discipline that earns it: the instant a component hard-codes a hex or rgb(), that surface stops responding to themes. Theming-for-free is conditional on no raw color ever escaping into a component rule.

Pair [data-theme] (JS/user controllable) with @media (prefers-color-scheme) (OS fallback) for full coverage.

Source: css-conventions skill §5.