Feature Request: Theme supersets / extensions.

[thijsdaniels]

Hi amazing VE community! I have a feature request :)

Background

I’m working on a design system using a Vanilla Extract theme. We build React components with this theme and multiple applications depend on this package, each with its own VE theme.

The package exports a theme contract, and each app calls createTheme with the exported variables.

Problem

Sometimes, an application needs additional tokens. We use three tiers of design tokens, including component-specific tokens, and apps may need extra components and therefore tokens. Although we could expand the original contract each time this happens, I'd like to avoid adding snowflakes to the original contract.

Proposal

I propose a way to define a new token contract on top of an existing one, preserving the original variables while adding new ones. For example:

In the design system package:

// @acme/ui/themes/themeContract.css.ts

export const variables = createThemeContract({
  colors: {
    primary: "",
  },
});

In a consuming project, extend the contract by passing it back into createThemeContract with additional values (this is the new bit):

// @acme/some-project/themes/themeContract.css.ts

import { variables as acmeVariables } from "@acme/ui";

export const variables = createThemeContract(acmeVariables, {
  colors: {
    primary: "",
    secondary: "",
  },
});

Then create a theme based on the extended contract:

// @acme/some-project/themes/myTheme.css.ts

import { variables } from "./themeContract.css";

export const myTheme = createTheme(variables, {
  colors: {
    primary: "red",
    secondary: "blue",
  },
});

This way, the package only needs to know about variables.colors.primary, while the project can use both variables.colors.primary and variables.colors.secondary.

I realize this might be a niche use-case, but it would be incredibly useful and, as far as I can tell, seems achievable.

Curious to hear your thoughts!