Token usage DX needs improvement...?

[manspaniel]

Coming from Stitches, and using it to build ~30 sites, our team have come to rely on it's excellent DX when it comes to design tokens. While Panda provides more advanced features, token consumption is a bit more confusing, inconsistent and verbose.

I'd like to highlight two of the overarching issues below.

Token Ambiguity

In Panda, it can sometimes be non-obvious when something is a token vs a regular CSS value.

// Panda
css({
  color: 'blue',
  fontSize: 'large'
})

Above, blue and large could refer to the standard CSS keywords, or they could refer to tokens defined in a custom Panda configuration. You can only be sure by checking the generated CSS.

On the other hand, Stitches token referencing syntax makes it very obvious.

// Stitches
css({
  color: '$blue',
  fontSize: '$large'
})

As an added bonus, tokens appear first in IntelliSense dropdowns when they start with $, and again, it is obvious which are tokens vs keyword completions.

(I am aware that this syntax can be enabled somewhat using the tokens:created as documented here)

Things get even more confusing if you use numbers as token identifiers.

// panda.config.js
tokens: {
  sizes: {
    1: {
      value: "40px",
    },
  },
}

// in other files...
css({height: 1}) // => height: 40px
css({height: 2}) // => height: 2px

Token Referencing

In Stitches, token referencing is very simple:

• $<token> implies var(--<scale>-<token>) (where the scale is inferred from the CSS property)
• $<scale>$<token> implies var(--<scale>-<token>)

This syntax gives Stitches very clear and concise token referencing:

// Stitches
css({ height: '$inputHeight' })
css({ height: 'calc($inputHeight + 8px)' })
css({ height: 'calc($inputHeight + $space$sm * 2)' })

The above syntax works as you expect, is easy to read/write, and is scalable from a single token-only value up to a complex calc expression, and works well for compound properties. Once you learn that tokens can be referred to using dollar signs, your intuition tells you that you can use them in calc/min/max expressions, and your intuition is correct.

Panda, on the other hand, is less intuitive:

// Panda
css({ height: "inputHeight" })
// => height: var(--sizes-input-height)
// ^Works, of course

css({ height: "calc(inputHeight + 8px)" })
// => height: calc(inputHeight + 8px)
// ^The calc expression is used verbatim, with no replacement 😬

To combat this, Panda has two (or three?) solutions:

css({ height: "calc({sizes.inputHeight} + 8px)" })
// ^Must wrap in braces, and prefix the token scale 😪

css({ height: "calc(token(sizes.inputHeight) + 8px)" })
// ^Use a pretend token() function inside the string itself. Again, the scale prefix is required 😪

Why do I need to write the scale explicitly? Is that by design, or just because it was too hard to make it infer the scale?

Curly braces just make more mess. And by writing token() I'm saving one character over a native CSS variable — saved by the dash.

var(--sizes-input-height)
token(sizes.inputHeight)

But then... despite requiring space prefixes on tokens when using token() and {token}... they are forbidden when using the simpler syntax, for some reason.

css({ height: "sizes.inputHeight" }) 🚫

You can also technically/sometimes use the token TypeScript function, not to be confused with the CSS function above 😳, along with a template literal:

import { token } from "@styled-system/tokens"
css({ height: `calc(${token("sizes.inputHeight")} / 2)` })

Except... the above code is not statically extracted, so the generated classname of h_calc(32px_/_2) will not have a definition unless your code happens to have css({ height: "calc(32px / 2)" }) in it somewhere else, in which case, yes it will work.

Obviously, this last approach is not one that anybody should use... but since token references don't always work how you/everyone expects, I bet a lot of people new to Panda have tried it. Panda's static extraction system could probably be modified to handle this silly third option, or it could just remain broken and confuse anyone who uses it — to me, the most appealing option is to make token referencing so intuitive that nobody would bother trying it.

[End of rabbit hole]

---

I hope my post doesn't come across as too negative. I really do want Panda to succeed, and appreciate the effort and commitment that has gone into making it.

But, I'm curious to know whether these issues have been considered/discussed, and if there are any ideas for addressing them? Am I alone in these concerns?

Cheers, Dan.

[astahmer]

Token Ambiguity

Above, blue and large could refer to the standard CSS keywords, or they could refer to tokens defined in a custom Panda configuration. You can only be sure by checking the generated CSS.

you can use strictTokens and strictPropertyValues if you want TS to throw errors when using unknown (not in config or in the predefined list of allowed CSS) values

I agree the automatic px, when numbers are used and no tokens is matching, should be removed

Token Referencing

the token category colors in {colors.xxx} is needed to differentiate between categories, as you could have the same token name for 2 (or more) token categories:

import { defineConfig } from '@pandacss/dev';

export default defineConfig({
  // ...
  theme: {
    extend: {
      tokens: {
        spacing: {
          "xl": { value: "40px"}
        },
        sizes: {
          "xl": { value: "32px"}
        },
        fontWeights: {
          "xl": { value: "72px"}
        },
      }
    }
  }
});

how would you know which one to use here css({ height: "calc(xl + 8px)" }) ?

---

• the token syntax (css({ height: "calc(token(sizes.inputHeight) + 8px)" })) is indeed made to match the syntax of a CSS variable, the difference is that when you use hash: true, you cannot know in advance which CSS var names to use, this syntax makes it possible

• the curly braces syntax (css({ height: "calc({sizes.inputHeight} + 8px)" }) is newer and was introduced to match the syntax allowed in config (people were asking "why isnt that working in runtime but is in the panda.config ?"), which itself mimics the W3C Token Format

• the JS (imported) token function is made to match the token syntax, and exists for dynamic styling, when things can't be extracted at build-time

• this css({ height: "sizes.inputHeight" }) 🚫 is not allowed directly because properties are bound to token categories through utilities, for example the height is in the [@pandacss/preset-base](

  panda/packages/preset-base/src/utilities/sizing.ts

  Line 100 in cca50d5

  values: heightValues,

  panda/packages/preset-base/src/utilities/sizing.ts

  Line 37 in cca50d5

  ...theme('sizes'),

  )

this syntax is however possible for CSS vars, css({ '--some-var': "sizes.inputHeight" }) ✅, as they are not bound to any token categories so you have to be specific

---

overall, I understand the complaint, it's not the first time it has been voiced: Panda is too flexible
I also heard the opposite a lot: I need X feature or why doesn't this work

just my personal opinion: by giving you a lot of features, you can choose to opt-in most of the time and start simple, then progressively use more if you need to
you can even treat Panda as a styling engine and build your own tooling on top of it
the opposite is not true, if Panda was minimal you'd just be quickly stuck and would move to something else

[manspaniel]

Thanks for taking the time to reply to me @astahmer 🙏

you can use strictTokens and strictPropertyValues

But then we have to use the square bracket escape hatch syntax, which just adds more friction and confusion.

I agree the automatic px, when numbers are used and no tokens is matching, should be removed

I love automatic px! It's such a DX win. I also love a numeric space scale... Stitches-style dollar sign token format solved this 💔

how would you know which one to use here css({ height: "calc(xl + 8px)" }) ?

The same way that css({ height: "xl" }) works — in that height maps the the size category implicitly.

If height: "xl" works, then height: "calc(xl + 2px) should work — because that's what the average dev will expect, because that's how variables work in the majority of languages, with fully-qualified names used to reach into a different scope.

• height: "xl" — this implicitly maps to the size category.
• height: "size.xl" — this explicitly maps to the size category.
• height: "space.xl" — this explicitly maps to the space category.
• height: "calc(xl + space.xl)" — this looks weird, but it should map xl to the size category and space.xl to the space category.
• "--custom-var": "calc(xl + 5px)" — this should throw/warn, xl needs to be qualified.
• color: "xl" — this throws, because there is no xl token in the color category.
• color: "size.xl" — this would work, even though it results in nonsensical CSS.
• border: "xl solid primary" — intuitively, this should work, and Panda should try it's best — the glaring edge case is a shared token name between color/borderWidths. How Panda deals with that edge case is an implementation detail, which shouldn't matter to a user until they encounter it.

No doubt curly braces would be necessary in most of the examples above, otherwise it's a parsing nightmare, but this seems like a no-brainer reference resolution system to me. It's easy to teach/learn, and easy to type/grok.

I say all this with only a casual understanding of how Panda works 😅 I'm sure it'd be a big change to implement something like this, with implications for utils and other parts of the API... but with Panda being less than a year old (publicly), now's the time to be led by design goals and DX, rather than existing/historic implementation details...

Just my 2c. Hope there's something interesting in my two essay posts!

[astahmer]

But then we have to use the square bracket escape hatch syntax, which just adds more friction and confusion.

how else would you like to solve this issue ? if I understand correctly you'd like to quickly discerne which value is a token from a raw value
currently you can either use a prefix for tokens to end up with the same thing as stitches or use strictTokens to enforce known values only, what issues remains with one (or both) of these approaches ?

---

height: "size.xl"

why not, tho now we'd have a 4th way of doing token referencing (height: "xl", height: "{size.xl}", height: "token(size.xl)")

The same way that css({ height: "xl" }) works — in that height maps the the size category implicitly.
If height: "xl" works, then height: "calc(xl + 2px) should work

how would you find the xl token in that string, just find and replace with some regex ? that would work fine most of the time, except when it doesn't

what if I have a xl token and a 2 token here: height: "calc(2xl + 2 + 28px)" ?
what if you need to use a spacing token ? e.g css({ height: "calc({sizes.inputHeight} + {spacing.2} + 8px)" })

I'm not saying it's not possible most likely won't be worth the effort

just seeing the examples you gave and I don't feel like it would make this intuitive, as it means using that new short syntax doesn't always work (whereas the existing syntaxes do)

[manspaniel]

But then we have to use the square bracket escape hatch syntax, which just adds more friction and confusion.

how else would you like to solve this issue ? if I understand correctly you'd like to quickly discerne which value is a token from a raw value
currently you can either use a prefix for tokens to end up with the same thing as stitches or use strictTokens to enforce known values only, what issues remains with one (or both) of these approaches ?

This stemmed from my original comment about how color: "blue" can mean anything, but was just highlighting one of a few ambiguities inherent to Panda, due to the decision to not require a token prefix. This doesn't concern me, because I prefer to enable a prefix.

height: "size.xl"

why not, tho now we'd have a 4th way of doing token referencing (height: "xl", height: "{size.xl}", height: "token(size.xl)")

Yup. But 5 because {xl} (see below)

The same way that css({ height: "xl" }) works — in that height maps the the size category implicitly.
If height: "xl" works, then height: "calc(xl + 2px) should work

how would you find the xl token in that string, just find and replace with some regex ? that would work fine most of the time, except when it doesn't

what if I have a xl token and a 2 token here: height: "calc(2xl + 2 + 28px)" ?
what if you need to use a spacing token ? e.g css({ height: "calc({sizes.inputHeight} + {spacing.2} + 8px)" })

I'm not saying it's not possible most likely won't be worth the effort

Sorry, I said immediately after my list of examples that No doubt curly braces would be necessary in most of the examples above, otherwise it's a parsing nightmare. I should have just included them for clarity.

To be clear about the syntax/resolution changes I'm proposing:

• Bracing — optional for simple values, required for any complex expression.
• Category prefixes — optional when the current property maps to that token group, required otherwise.

eg. These are equivalent. Bracing is optional:

• height: "lg"
• height: "size.lg"
• height: "{lg}"
• height: "{size.lg}"

Same here:

• height: "space.lg"
• height: "{space.lg}"

Bracing not required for !important directives.

• height: "space.lg!"

Also equivalent, but bracing is required:

• height: "calc({inputHeight} + {spacing.2} + 8px)"
• height: "calc({size.inputHeight} + {spacing.2} + 8px)"

Invalid/left untouched:

• height: "calc(inputHeight + 2 + 8px)"

just seeing the examples you gave and I don't feel like it would make this intuitive, as it means using that new short syntax doesn't always work (whereas the existing syntaxes do)

Hope the above section clarifies my last post. I'm suggesting methods to iron out the inconsistencies in how tokens are consumed, because I can see how it can be confusing and frustrating to Panda newbies. I'm about to transition our dev team over to Panda, for all new work, and this is one of the things which I can see being an issue.

[anubra266]

@manspaniel IMO, the way to iron out inconsistencies in the team would be to agree on practices for the team, not overconfigure the styling engine.

When the team agrees with said practices, they can then be enforced:

• With config options where available; e.g. strictTokens to ensure tokens only
• With eslint plugin; e.g. ensuring devs don't opt out of tokens with escape hatch (More rules can still be added to this)

We'll all have opinionated ways of going around things in our different teams, and it'll be inefficient for panda to try to satisfy all these.

[manspaniel]

I know how to iron out inconsistencies in a team... I'm talking about inconsistencies in Panda.

Literally asking for more expressiveness and y'all keep recommending that I enable options that make Panda less expressive...? Stitches solved token scoping/cross-referencing years ago and it's basically what I'm describing. It's the most expressive syntax because of it's simplicity, and paired with Panda's tooling/functions it'd be killer...

But it's clear there's strong resistance to a rethink of this part of Stitches, so I'll drop it.

Thank you both though for the replies and discussion.