Theme switching retargets the semantic layer, not raw values

What it is

A theme is not a second copy of every number. It is the same set of semantic names pointed at a different set of primitives. In light, color.bg.default aliases to a near-white; in dark, to a near-black. Call sites keep writing the semantic name, never the near-white. Semantic alias retargeting is the mechanism of a theme swap.

This is one product’s suite of appearances (light/dark, high contrast), not several brands each swapping a whole semantic table — that is a different product-identity problem. It is also not “theming” to mutate a primitive: primitives are materials, and a global material swap drags every role that happened to share that material.

Why it happens

A theme file is a lookup table: semantic name → primitive, one table per theme. Runtime (or build) replaces the table; the component tree does not move. Switching at the primitive layer — turning gray.0 from white into black — moves every role that referenced gray.0, including roles that should not follow the theme (print near-white, a brand accent that stays put). The semantic layer is the stable roster of roles allowed to change; theme authors only retarget pointers.

A call site that wrote a primitive cannot be driven by the theme table, however complete the table is: that node keeps emitting light paint in dark mode. Theme capability is therefore not “two palettes exist.” It is whether every call site sits on the semantic layer. Multi-brand work, by contrast, replaces the values of an entire semantic table for a different product identity, not day/night on the same UI.

Where it stops holding

Forced-colors modes (Windows high contrast, some reading modes) let the OS own the palette; product aliases are overwritten and cannot be assumed to hold. Pipelines with no runtime theme (some print, some native splash screens) can only emit a single flattened build. A user-chosen accent that never entered the semantic table will dangle or fall back to a hardcoded value when the theme flips. HTML email often can only ship two static skins, not retarget aliases on the client.

Applying it

• Keep one semantic-to-primitive table per theme. Component files must not contain light-only or dark-only literals.
• Screenshot the same component tree under both tables. Do not author a second component set for dark.
• Mark roles that must not follow the theme (logo paint, always-sufficient status color) as fixed aliases, off the swappable table.
• How to check: swap only the lookup table, touch no component, and inspect the dark screenshots. Any node that still holds a light-mode literal is a call site sitting on the value layer.

Related

• Same group: R1.01.1 Tokens turn design decisions into named, distributable values · R1.01.2 Semantic tokens and primitive tokens need separate layers · R1.01.3 Using raw values directly bypasses the system
• Nearby: R1.15 Multi-brand and multi-theme · R1.09 Token layers and semantic naming
• Search terms: semantic alias retargeting · theme swap · semantic layer