Dynamic Color Customization with StyleX - Best Practices?

[BMCwebdev]

Heyo everyone,

We’re starting to introduce customization capabilities into our design system, with a small, focused goal: allowing users to choose their primary color.

Background

Currently, we have a library of tokens built with defineVars, where we use readable string keys as the names, as requested by our design team.

export const colorPrimitives = {
  "--s-color-neutral-0": "#ffffff",
  "--s-color-neutral-100": "#f8f8f9",
  // ...
};

We also define semantic tokens that point to core tokens to provide an abstraction layer:

export const colorSemantic = {
  "--s-color-primary": "--s-color-peri-500",
};

export const coreTokens = defineVars({
  ...colorPrimitives,
  ...colorSemantic,
...

The Challenge

We want to enable users to dynamically change the primary color at runtime (e.g., based on API data or user preference).

I’ve looked into using createTheme, but it seems to be intended for static values known at build time. Since our customization might come from an API or user settings, this approach doesn’t seem feasible.

One potential solution I’ve considered is directly updating the CSS variables at the html or body tag level. Since we use named variables rather than hashed ones, this might be manageable. However, it feels a bit off given StyleX’s default behavior of hashing variable names, and I wonder if there’s a more “StyleX-native” way to handle this.

Also, I’d like to avoid using inline style attributes.

Question

Has anyone tackled dynamic theme customization with StyleX, especially where the colors are not known until runtime? Are there best practices or recommended approaches for this kind of use case?

Any guidance or examples would be greatly appreciated!

Thanks!

[BMCwebdev]

The only solution I can think of, if you’re using the default StyleX hashed variable names, is that you would point your hashed variable to a named variable (—s-color-primary) and then use JS to fetch the custom color value and redefine that named variable further down the tree.