Allow partial token replacements without resetting all theme variables with ScopedTheme

[brunowilliang]

Hi team,

I am using ScopedTheme and custom themes for page branding.
I need to keep base light / dark behavior, but override only two tokens in scoped templates:

• --accent
• --secondary

Current behavior

When I define templates with partial overrides, Uniwind requires every theme to include the full variable set and throws:

• Uniwind Error - Theme <template> is missing variable ...
• Uniwind Error - All themes must have the same variables

So for small branding changes (2 colors), I currently need to duplicate dozens of tokens in every template.

Repro setup (simplified)

metro.config.js

withUniwindConfig(config, {
  cssEntryFile: './src/theme/global.css',
  extraThemes: [
    'red-green-template',
    'magenta-lime-template',
    'gold-blue-template',
  ],
})

global.css (intended partial overrides)

@layer theme {
  :root {
    @variant light {
      --accent: oklch(...);
      --secondary: oklch(...);
      --background: oklch(...);
      --foreground: oklch(...);
      /* full base token set */
    }

    @variant dark {
      --accent: oklch(...);
      --secondary: oklch(...);
      --background: oklch(...);
      --foreground: oklch(...);
      /* full base token set */
    }

    @variant red-green-template {
      --accent: oklch(63.73% 0.2096 16.63);
      --secondary: oklch(69.64% 0.073 139.08);
      /* expected: inherit all other tokens */
    }

    @variant magenta-lime-template {
      --accent: oklch(64.86% 0.1335 316.07);
      --secondary: oklch(84.09% 0.1033 103.28);
      /* expected: inherit all other tokens */
    }

    @variant gold-blue-template {
      --accent: oklch(91.36% 0.1279 59.15);
      --secondary: oklch(44.92% 0.3234 213.84);
      /* expected: inherit all other tokens */
    }
  }
}

Usage

<ScopedTheme theme="red-green-template">
  <MySection />
</ScopedTheme>

Expected behavior

Scoped themes should support partial token overrides and fallback/inherit missing tokens from the active base theme (light or dark), instead of requiring full token duplication.

Possible approaches:

1. Theme inheritance (custom-template extends light/dark)
2. ScopedTheme API for CSS variable overrides (subtree-level)
3. Automatic fallback for missing variables to base theme

Why this matters

For multi-tenant/page-branding scenarios, changing only accent and secondary is common.
Requiring full token duplication for each template is hard to maintain and error-prone.

Is there a recommended way to implement this today?

[Brentlok]

Hi, to answer your question directly: we do not currently support extended or partial themes. Right now, Uniwind strictly enforces that all themes have the exact same variable set to guarantee predictable switching and prevent missing-token errors at runtime.

It's definitely a pain point to duplicate all those tokens, but I'm not sure what "inherit all other tokens" should actually do.
Some scenarios:

• If a component is wrapped in , should it inherit missing tokens from the nearest parent (or the root provider)?
• What happens if the app toggles between light and dark modes? Should red-green-template automatically inherit from light when the app is in light mode, and dark when it switches to dark mode?
• Do we need to introduce syntax to explicitly declare inheritance (e.g., something conceptually like red-green-template extends light), or should the fallback be purely based on the runtime React tree hierarchy?

If we just fall back to the "previous" theme in the tree, things could get unpredictable depending on where the ScopedTheme is placed.

[brunowilliang]

hey @Brentlok, thanks, that clarifies it.

What I’m asking for is basically a scoped version of updateCSSVariables:

• apply overrides only inside ScopedTheme (not globally),
• e.g. override only --accent and --secondary,
• resolve missing tokens from the selected base mode (light/dark) in a deterministic way.

That would cover branding use cases without duplicating full theme token sets.

[Brentlok]

As a maintainers, we have to balance these specific feature requests against the overall simplicity and performance of the library. Our goal with Uniwind is to cleanly support about 95% of common use cases without bloating the core API or sacrificing performance.

Implementing scoped CSS variables under the hood would actually introduce a major maintenance burden on our end. Specifically, it would require:

• A new Context layer: We'd need to add another React context specifically for tracking and passing down scoped overrides.
• Caching complexity: It would introduce significant complexity into our caching strategies, as tokens would no longer be strictly static per theme.
• Hook resolution overhead: It complicates the logic for how our hooks resolve the currently active tokens, adding runtime overhead and a new surface area for bugs.

We simply don't have the capacity right now to support and maintain this level of nested theme granularity.