Review Token-Aware usage

[peduarte]

A discussion regarding the API of token-aware values emerged from a call and was then mentioned here #78

Im moving that to its own issue, so we can make a call on how to move forward and no pollute the negative value issue, although they'll be somewhat impacted by each other.

Option 1 - current

So, currently, token-aware values are completely seamless:

{
  backgroundColor: "primary", // maps to colors.primary
  padding: "3", // maps to space[3]
}

The main benefit of this is that its seamless, and it feels great to use! Styled System introduced this and overall it had a good reaction. Although I believe that devs that haven't fully experienced this generally seem to have a negative reaction to it.

On the downside, if it's mistyped, it's not possible to know - because all values also allow strings. So, backgroundColor: "prmay" won't throw any errors, but you won't get what you expect, since prmay is not a token nor a valid css colour value.

It's also harder to refactor, so if you rename primary to something else, you need to manually refactor the code.

Then, there's the issue with using negative values. With TS we cant dynamically add keys to an object, more info #78 (comment)

Finally, the mapping of CSS Properties to Theme Scales is automatic, and this could be a seen as a good or a bad thing. Its fair to assume you may nearly always want values from a specific scale, but, I don't think its safe to say that it's always the case. So that means, escape hatch will need to be introduced.

---

Option 2

In this comment, @hadihallak suggests prefixing the tokens, so something like:

{
  backgroundColor: "$primary", // maps to colors.primary
  padding: "$3", // maps to space[3]
}

I like this because its a bit more explicit that its not a raw CSS value, but still easy to type. No need to interpolate, or import anything else.

On the other hand, however, I think it would have the same issues with TS and negative values. But please correct me if Im wrong here @hadihallak. The refactoring issue mentioned above exists here too.

As with the example above, it also relies on the automatic mapping of CSS Properties to Theme Scales.

Note: This is actually already possible, but users need to do it themselves.

---

Option 3

Another option is a function:

{
  backgroundColor: token('colors', 'primary')
  padding: token('space', 3)
}

I like this because its explicit what is happening, it gives the users the ability to pick the scale, and its type safe.

I think it would still have a refactoring issue mentioned above.

There's the extra chore of having to import the token function all the time, personally, I really dislike this, and think it has a big weight on the DX.

---

Option 4

Finally, we could receive the theme object

t => ({
  backgroundColor: t.colors.primary
  padding: t.space[3]
})

I like this because its a pattern people are used to. Typing wise seems pretty straight forward as it would be inferred from th object keys. Its easy to refactor. Its quite explicit, so no confusion between tokens and raw CSS values.

The only downside I can think of is that you need to wrap the object in a function, but that's not a big deal I think?

This approach could also work with Option 3, instead of receiving the object, it receives a token function

---

Finally, it's worth mentioning that currently the library is trying to be the least opinionated as possible. So if users wish to prefix their tokens, they can already do that!

tokens: {
  colors: {
    _red: 'tomato',
   BLUE: 'royalblue'
  }
}

styled('div', {
  backgroundColor: '_red',
  color: 'BLUE'
})

So I think we should consider the friction the library introduces too. Perhaps being too opinionated isn't a good idea

[peduarte]

A bit of an update. After lots of different discussions with different people, it seems that it all comes down to:

• easy and convenient DX
• differentiate a token from a value
• know if they're using an invalid token with escape hatch
• escape hatch to set a value from a different scale (eg: marginTop maps to sizes scale)

I think the way the library currently is, people can choose their conventions. This is really good. This means that people can tick the boxes they need.

For example:

const { styled } = createStyled({
  // know if they're using an invalid token. optional, defaults to `false`
  strict: true,
  tokens: {
    colors: {
      // easy and convenient DX
      // differentiate a token from a value
      $black: '#111',
      $red: 'tomato'
    }
  }
})

const Component = styled('div', {
  // easy and convenient DX
  // differentiate a token from a value
  backgroundColor: '$black',

  // not a token
  color: 'red',

  // know if they're using an invalid token
  borderColor: 'primary' // TS error, this is not a token

  // know if they're using an invalid token
  borderColor: 'primary' as any // make explicit that you don't want to use a token
})

☝️ This ticks most of our boxes:

• easy and convenient DX
• differentiate a token from a value
• know if they're using an invalid token with escape hatch and optional
• escape hatch to set a value from a different scale (eg: marginTop maps to sizes scale)

The only thing missing is the ability to receive the theme, in case people need access to other scales.

For that, I propose:

const Component = styled('div', t =>({
  // set padding top based on the sizes scale
  transform: translateY(t.sizes[4])
}))

• escape hatch to set a value from a different scale (eg: marginTop maps to sizes scale)

[VinSpee]

A bit of an update. After lots of different discussions with different people, it seems that it all comes down to:

…

• differentiate a token from a value

…
For example:

const Component = styled('div', {
  // easy and convenient DX
  // differentiate a token from a value
  backgroundColor: '$black',

  // not a token
  color: 'red',

  // know if they're using an invalid token
  borderColor: 'primary' // TS error, this is not a token

  // know if they're using an invalid token
  borderColor: 'primary' as any // make explicit that you don't want to use a token
})

I'm still not quite clear. How does this look with sizing tokens? There's still the problem of numeric values being converted to px automatically, right?

For me, this is my primary concern with the library. I don't want to let someone do the "wrong thing" easily:

const Component = styled('div', {
 // gives me 1px, when I want it to give me `theme.sizes[1]`. The "wrong" thing (using actual pixel values in line), but written in a convenient way (granted, the same way that react's `style` would have you write it)
  marginBottom: 1,

  //gives me `theme.sizes[1]`, right?
  marginBottom: '1',

  // the "wrong" thing, but clearly on purpose.
  marginBottom: '1px'
})

[peduarte]

Yeah, I get it. Since I wrote this issue, we've kinda agreed on a best practice. Which is to prefix your tokens.

We chose to prefix it with $. That makes it clear to to know when you're using a token.

const Component = styled('div', {
 // gives me 1px, when I want it to give me `theme.sizes[1]`. The "wrong" thing (using actual pixel values in line), but written in a convenient way (granted, the same way that react's `style` would have you write it)
  marginBottom: 1, // 1px just like React, SC, Emotion, Styled System Theme UI

  marginBottom: '$1', // tokens.space.$1

  marginBottom: '1px' // 1px
})

[VinSpee]

I understand.

marginBottom: 1, // 1px just like React, SC, Emotion, Styled System Theme UI

for clarification, I don't think that's how styled-system works: https://codesandbox.io/s/styled-systembasic-demo-ex4gf?file=/src/index.js:872-926

am I missing something there?

[peduarte]

Not sure why it doesnt work in py but if you add it to pl it does.

[emadabdulrahim]

@peduarte Enjoyed reading this write up. Very thorough walk through of the problems.

Excited for strict mode to land.

+1 for the function that receives theme object to access any value from the theme directly when needed.

Overall I'm excited about the direction and perspective that Stitches is taking.