Support resolving object-based tokens to base CSS values in style() for better design token ergonomics

[mariuslundgard]

Hi all 👋

I wanted to open a discussion about improving the ergonomics of consuming design tokens with vanilla-extract, specifically when tokens are represented as objects with both a “base value” and nested variants.

Context / Problem

Many design systems expose token APIs where a token group has a base value and variants, for example:

vars.color.fg.$            // 'var(--color-fg)'
vars.color.fg.muted        // 'var(--color-fg-muted)'
vars.color.fg.link         // 'var(--color-fg-link)'

This shape is useful because:

• tooling like Figma only has leaf-only variables,
• people want color.fg and color.fg.muted semantics,
• and it avoids artificial keys like default.

However, in vanilla-extract today, passing an object token like vars.color.fg into style() isn’t supported directly because it’s not a string. This leads to workarounds such as forcing a .base/default key, inverting the object hierarchy, or abandoning a clean grouped API entirely.

What I’d love to see is:

style({
  color: vars.color.fg // resolves to vars.color.fg.$ implicitly
})

style({
  color: vars.color.fg.muted // resolves to the specific variant
})

Why this matters

• It enables a typed, dot-chained API with variants while avoiding awkward default naming.
• It aligns with how many design systems keep tokens grouped, especially when CSS variables may be hashed or autogenerated.
• It improves IntelliSense discoverability (without losing ergonomic access to the base value).

The idea is not to change the runtime output or core CSS API — just to enrich how style() (and similar consumers) accept a token object by resolving it to its base string when appropriate.

Possible user experience

• Dot-chaining works nicely (vars.color.fg, vars.color.fg.muted, vars.color.fg.link).
• No need for artificial “default” or “base” keys in API.
• No loss of variant support.

Questions / open points

• Is it somehow possible to make compatible with vars in strings? E.g.

  border: `1px solid ${vars.color.border}`
  

• Should the resolution rule be convention-based (e.g. $ or value)?
• Should this apply to all property consumers or only style()?
• Are there existing patterns in vanilla-extract that could be extended here?

Happy to iterate on the details — thanks for considering it! 🙏