Unable to get underlying raw color value when token is defined as a reference

[etlovett]

Description

When a token or semantic token is defined as a reference to another token or semantic token, it appears that there is no way to retrieve the actual underlying color value. It looks like the token function is only doing one level of "dereferencing", but there are scenarios where it's necessary to have the underlying raw color value (e.g. hex), so given how the docs at https://panda-css.com/docs/theming/usage#style-attribute are written I was expecting token to do as many dereferencing steps as necessary to get to the actual underlying color value.

To get more concrete... In the playground I have hex and semanticHex tokens that have a hex value defined, and then I have reference and semanticReference tokens that refer to their hex counterpart. In the React component I then print both token() and token.var() output for each of these four. You can see that token() appears to return the underlying value only down one level, so the hex tokens produce a hex value and the reference tokens produce the CSS variable for the hex token. I would expect token() to return a hex value for both, by following the chain to get the hex value for the hex token rather than stopping after a single dereference.

Is there another way to get the underlying raw color value for tokens defined as references? Or is there a reason token() couldn't be changed to return the underlying raw value? Thanks!

Link to Reproduction

https://play.panda-css.com/bNuMXWtXgN

Steps to reproduce

1. Open playground
2. Observe strings in the output

JS Framework

No response

Panda CSS Version

0.36.0

Browser

No response

Operating System

• macOS
• Windows
• Linux

Additional Information

No response

[astahmer]

but there are scenarios where it's necessary to have the underlying raw color value (e.g. hex),

hey, can you give a bit more informations as to what you're trying to achieve ?

you could get the raw value directly in the browser using getComputedStyle

[etlovett]

We're using a third-party library for some of our UI that (unfortunately) requires the underlying color value so that it can parse it to generate adjacent colors from. For example, it generates a lighter version for a themed overlay. It would be nice to be able to pass it the underlying hex value by "extracting" it from the theme in our Panda config, rather than needing to duplicate the underlying hex values to the location where we need to pass them to this library.

[astahmer]

understood ! seems like getComputedStyle should solve this use-case

[etlovett]

I agree that it would totally make sense for token() to do the same thing in both JS and CSS. But is that actually what's happening? For example, in this edited version of the original playground, the code css({ color: 'token(colors.semanticReference)' }) produces the CSS .text_token\(colors\.semanticReference\) { color: var(--colors-semantic-reference); }. Doesn't that therefore mean that token() in CSS does the same thing as token.var() in JS, not token() in JS?

That's why my mental model was that token() in JS was about getting the underlying value. But perhaps this isn't what would be best!

Given the above, I can see a two different possible API shapes...

Option 1 (current mental model, minimal breaking changes):

• token(): does the same thing as today, i.e. one level of dereferencing. So token(colors.semanticReference) produces 'var(--colors-semantic-hex)'
• token.var(): returns the CSS variable for the token, i.e. matches token() in CSS. So token.var(colors.semanticReference) produces 'var(--colors-semantic-reference)'
• token.raw()/token.underlying() (or whatever name): returns the actual color value for this token, by doing as many levels of recursive dereferencing as necessary. So token.raw(colors.semanticReference) produces '#0000FF'

Option 2 (the mental model is that token() should have consistent behavior between JS and CSS):

• token(colors.myColor): does the same thing as in CSS. So token(colors.semanticReference) produces 'var(--colors-semantic-reference)'
• token.raw()/token.underlying() (or whatever name): returns the actual color value for this token, by doing as many levels of recursive dereferencing as necessary. So token.raw(colors.semanticReference) produces '#0000FF'
• Optionally, add an API to do one level of dereference the way that token() in JS does today. So token.___(colors.semanticReference) produces 'var(--colors-semantic-hex)'

What do y'all think? Am I misunderstanding things or do I still have an incorrect mental model? Or what sort of API design do you think would be best?

[etlovett]

seems like getComputedStyle should solve this use-case

Thinking about this more deeply, I've realized that this might unfortunately actually be the only way to do this!

The problem is that we're using semantic tokens that reference semantic tokens whose values are driven by Panda conditions. The fact that there are conditions involved means that the underlying values can vary across the application, and therefore are only knowable at the point we render the third-party library.

We therefore have to do the following:

1. Have a DOM element that:
   1. Is a sibling to the third-party library's root DOM node
   2. Is hidden from both the UI and screen readers
   3. Has a React ref attached to it
   4. Has the colors we care about used in various CSS styles
2. After render, use getComputedStyles to extract each of the styles we set in 1.iv.

And the use of getComputedStyle means that this cannot be done during server-side rendering -- this part of the React tree will have to be marked with a 'use client' so that it React Server Components do not render it on the client.

This is pretty unfortunate, but I don't know of another way to do it without duplicating the color values or somehow sharing code between the Panda config and our runtime code.

Please let me know if you think there's something I've missed that would make this easier! Otherwise I think the only potential new API Panda could have would be a hook that returns both a DOM element to insert and the resulting color value, handling all the other stuff under the hood. This API would work, but it's a bit of a departure from the way the rest of the codebase works.

[etlovett]

That said, y'all may still want to make sure you have a consistent framing to use when discussing the behavior of token(). It could be any of these three mental models:

1. "token() is consistent across JS and CSS, so it should return the variable for a semantic color"
   • In my playground, this means token('colors.semanticReference') === 'var(--colors-semantic-reference)'
2. "token() is consistent across (regular) tokens and semantic tokens, so it should return the value that's only one dereference away if there's no condition involved"
   • In my playground, this is token('colors.semanticReference') === 'var(--colors-semantic-hex)'
3. "token() is consistent across (regular) tokens and semantic tokens, so it should return the most-dereferenced possible value, stopping the dereference only when we hit a raw value or an active condition"
   • In my playground, this is token('colors.semanticReference') === '#0000FF'

In this framing, #2349 changed from mental model 1 to mental model 2.

FWIW I think that mental model 2 is likely the least attractive option; it seems like a version of mental model 3 that just provides slightly less user value since the result of token() is more likely to be a CSS variable and not the underlying raw value.