Token Theming

Token theming is the layer where semantic tokens earn their keep. You define primitives once. Blue 500 lives at #3B82F6 forever. Semantic tokens like color-surface-default color-text-primary and color-interactive-primary then point at whatever primitive fits the active theme. Light mode points color-surface-default at #F8FAFC. Dark mode points the same token at #0F172A. High-contrast mode points it at pure black. The button card or nav that references color-surface-default never updates its code. It reads one token name and the system handles the rest. This turns themes from scattered CSS overrides into a single data swap. Your components stay clean because they consume roles instead of raw values.

Token theming is not duplicating every Figma frame for dark mode. It is not maintaining separate CSS files that drift out of sync the moment someone tweaks a hover state. It is not dropping primitive tokens like color-blue-600 straight into your components. That single mistake breaks every future theme. It is not a fix for weak contrast ratios or sloppy color choices. If your light palette fails WCAG your dark version will fail harder. Token theming also fails hard when teams invent vague names like accent-dark-2. The whole system collapses without strict category-role-variant-state naming.

GitHub Primer shows exactly how it works at scale. In 2024 Primer ships four themes from one React codebase: light dark dark-dimmed and dark-high-contrast. The functional token --color-fg-default resolves to #24292F in light mode and #F0F6FC in dark. The same token name controls body text across every repository issue and pull request. Flip the data-theme attribute on the html tag and CSS custom properties update the entire UI with zero component changes. Shopify Polaris uses the identical model. Their token --p-color-bg-surface switches from off-white to deep slate while the merchant admin components stay untouched. One JSON update from their design team and every Shopify store reflects the change overnight. IBM Carbon pushes the model into enterprise territory with layered surface tokens. A modal sitting on a panel sitting on a page each pulls its own semantic surface token. Carbon maintains separate mappings for all four themes inside Style Dictionary which then spits out web Swift and Kotlin files. Atlassian repeats the trick for Jira and Confluence. Their color-background-neutral-bold token shifts from cool gray to warm charcoal across themes. Teams there report cutting dark mode maintenance by 80 percent because no one touches individual screens anymore.

Figma finally caught up in 2023 when it shipped variable modes. You now set color-surface-default once per mode inside the same variable collection. Export once and both designers and engineers work from the same source of truth. The CSS looks like this. Root defines the light values. The data-theme=dark selector reassigns every semantic token to its dark primitive. Add a data-theme=high-contrast selector and you have three modes with one set of components. Tools like Tokens Studio plus Style Dictionary turn the Figma file into production JSON so no human copies hex codes anymore.

Use token theming the moment your product ships to real users who expect system-level dark mode. Use it when you support enterprise clients demanding high-contrast themes for accessibility compliance. Use it when your design system feeds three or more products or when marketing decides to refresh the brand every twelve months. The first time you change one primitive and watch every primary button across every theme update you will never go back. The semantic tier becomes your single source of truth for every visual decision.

Skip token theming on a marketing landing page that lives only in light mode. Skip it during the first eight weeks of a new product while you validate flows and throw away screens daily. A solo designer or two-person team iterating fast gains nothing from maintaining theme mappings. Bad naming discipline makes it worse. Premature tokens named color-dark-blue create more debt than simple hardcoded values. Wait until the UI stabilizes and you understand the real roles before you add the semantic layer.

The payoff arrives when you combine token theming with sparse component tokens. Most elements consume semantic tokens directly. Only deliberate exceptions like a destructive button get a component token that points at color-feedback-critical instead of color-interactive-primary. Change the critical red once in the primitive scale and every warning banner error state and delete button updates across all themes at once. Teams that master this stop treating dark mode as a separate project. It becomes config not code.

Token theming turns a maintenance nightmare into a one-line config change.