Document limitations of tokens passed to stitches

[smhutch]

Bug report

Not exactly a bug with stitches, but more of a limitation of css variables.

Describe the bug

Certain token keys create invalid css variables tokens. For example:

const theme = {
  colors: {
    test: "black", // ✅ works, of couse
    "test-test": "black", // ✅ works
    test_test: "black", // ✅ works
    "test.test": "black", // ❌ breaks
    "test/test": "black" // ❌ breaks
  },

For cases which break, the CSS variables created look something like: var(--colors-test)/test

To Reproduce

Steps to reproduce the behavior, please provide code snippets or a repository:

1. Sandbox
2. Check dev tools for divs with white backgrounds

Expected behavior

Support any string as a token key, or warn when an invalid one is used.

Screenshots

n/a. See Sandbox

System information

• OS: macOs
• Browser (if applies): n/a
• Version of Stitches: 0.1-canary.20
• Version of Node.js: 14

Additional context

This certainly might be won't fix issue. In my case I hoped to use this structure: test/test because our design tokens are also used in other places (Figma), and we hoped to keep them identical in code and design.

[cappuc]

I encountered the same problem and I was thinking that a workaround this limitation of css variables can be to replace invalid characters with a mapping to a valid string when generating the css variable name.

For example:
. -> -dot-
/ -> -slash

So the generated variable names of your example will be:
test.test -> var(--colors-test-dot-test)
test/test -> var(--colors-test-slash-test)

[jonathantneal]

I totally understand the desire for this. If you want a short answer it’s this: This request will break some strong expectations in CSS. Whenever possible, we try to avoid breaking the syntactics or implicit semantics in CSS.

---

Now, if you are interested in a deeper explanation:

Our $ tokens loosely follow the CSS "ident" token ("ident" is short for "identifier"). All keywords, properties, custom properties, at-rule names already follow this rule. These are tokens that identify things. People get used to them, even if they don’t know how they really work.

Here’s how an "ident" token really works:

These syntactic rules allow CSS to safely add new features and improve the CSS authoring experience without breaking backward compatibility. For instance, the slash (/) has recently become the common way to separate arguments, similar to the comma (,) in JavaScript. We already see it used in the new color syntaxes like rgb(0% 0% 100% / 50%). Therefore, even if decided to drop the syntactic rules for /, doing so would break its implicit semantics.

For our $ tokens, we introduce a superset to CSS that is a kind of "ident", only it follows looser parsing rules.

The looser rules are copied from the CSS "hash" token, only ours substitute # for $ .

Following these rules means we keep Stitches predictable. However, it also means we accept certain restrictions. Neither the "ident" or "hash" tokens support a period (.) or slash (/) as a separator. If we change our superset to support those characters, we will experience unexpected breakage with either the syntax or semantics of some CSS that is already out today or coming in the future.

So we live with the restrictions. Tho, I promise you, we are constantly searching for more clever ways to work with those restrictions, or ways to work around them. 😄

[smhutch]

Thanks for the detailed explanation @jonathantneal. I too can live with these restrictions, and hesitated to even open this issue since I realised it seemed like an upstream issue (CSS itself being upstream 😄).

That said, do you think it would be worth adding a short note to these docs to flag that certain characters are not supported (at least . and /)?

[jonathantneal]

I think that’s an excellent idea, and worth adding to the documentation. What do you think about leaving this open until we add it to the docs, @peduarte ?

[peduarte]

@jonathantneal noted! 💯

[peduarte]

Done stitchesjs/stitches-site@0645af3