feat: rework base theming architecture

[mellyeliu]

Context

Reworking the general theming infrastructure from #16

The theming flow looks something like this:

• All raw hex/rgb/static values for colors, spacing, etc are stored in defineConsts calls. defineConsts transpiles to a plain JS object that is inlined at build time, generates no CSS, and its values can be imported and used within stylex.create or stylex.defineVars files as needed.
  • Alternatively, we can still use raw JS objects if we never need to use these in create calls and we don't care about repeating across files. But it'll get messy
• defineVars uses the defineConsts values and -- keys, which expose the variable name and allow users to modify them as CSS variables anywhere.

export const colorRaw = stylex.defineConsts({
    '--xdsAccent': colorTokens.accent,
    '--xdsSurface': colorTokens.surface,
    // ... map all tokens
  },
});

export const colorTokens = stylex.defineVars({
   '--xds-accent': colorRaw['--xdsAccent']
   '--xds-surface': colorRaw['--xdsSurface']
});

export const neutralColors = stylex.createTheme(colorTokens, {overrides})

// Not settled on the shape of the export here or the keys we want to expose, but we can iterate
export themeTokens = {
   colors: colorRaw,
   ...
}

There are two primary issues to using create/props instead of defineVars/createTheme in #16

1, Losing the VarGroup guarantee that each theme sets all variables (and unset keys are reset)
2. It creates a single class to set all variables and not one class per variable. (performance critical)

Blockers/Todos

• Replace camelCase keys with -- in defineConsts?
• Reuse base token values across tokens + defaultTheme + neutralTheme
• Refactor, clean types, update docs

One option is to also use -- keys in defineConsts as well instead of the camelCased key for ease of use. Currently we disallow such keys in defineConsts for relatively arbitrary (safety/obfuscation) reasons but opening facebook/stylex#1460 as an option to fix this

We could have a system that maps cleanly from defineVars -> defineCosts (one camel cased, another --)

Testing

Storybook theming works

Screen.Recording.2026-01-23.at.9.28.25.PM.mov

[mellyeliu]

this does in fact work within StyleX, although it's a bit hacky

[mellyeliu]

As discussed with @cixzhang, went with a raw vars object exposing hex values -> passed to defineVars -> themed using `createTheme

Split docs changes into #50 as the PR was getting unwieldy

[cixzhang]

Nice! Thanks for updating this and making the theming system better!

I guess we didn't want to prefix with --xds? Maybe something we can revisit later or perform prefixing using a plugin if we end up white gloving this system. I do like the conciseness.

[mellyeliu]

Yeah, I mainly left out the prefix for now in case the naming discussions weren't stabilized. We can always update or tweak it later!