RFC - Design Tokens Structuring

[anitavincent]

RFC Design Tokens Structuring

Problem

We overcomplicated the implementation of our current tokens, we currently use css variables, but they are not visible to the design system users (developers). They are built in runtime, which hinders performance and makes them inaccessible in css form for developers while coding. Having the raw variables unavailable for developers forces them to use our current style framework to have access to our design tokens and theming, instead of having the possibility of using any styling method they prefer. This attachment between style framework and tokens also makes it very difficult for us to change between different libraries and frameworks when we need it.

Why this matters?

Theming is an important theme (ha) when discussing a design system that serves an admin used by different companies with their own brands. Our current solution doesn't easily support the generation and usage of different themes. It is also not future-proof as it doesn't offer flexibility for developers or for our own future changes.

Proposal

Summary

Transform all design tokens into CSS variables that are exported and can be used by developers directly. Use these variables to build token integrated js styling solutions, instead of implementing tokens and js styling solutions together.

Current model

• We have tokens associated with values inside objects but hidden inside the implementation of our styling functions (csx, useTheme)
• If a developer wants to use a token value they must use one of our core js functions
• We offer only one css styling framework (stitches) and it's intertwined with the implementation of tokens

Proposed model

• We have tokens stored in css files that are exposed to developers
• A developer may use the styling tools we offer which already includes our tokens, but they can also use css variables to get the raw token values
• We offer more than one css styling framework, they consume our tokens, but their implementation doesn't require changes on the tokens. Developers may create their own css styling framework or libs as well

Details

We'll have a package exclusively for tokens. It will have scss files with the definition of css variable that will be exported for use.

Css in js helpers might be implemented and may use the tokens, but will not be defined in the same package, and they will not be a dependency for the token package.

Pros

• Isolated tokens enable the implementation of different styling libraries while keeping the same tokens
• Developers are free to handle styling how they prefer
• Theming becomes a simple matter of editing css variables
• We have more freedom to adapt our styling framework while keeping core style definitions

Cons

• Future breaking changes potentially affecting more stakeholders

Unresolved questions

• Are users alowed to use raw token values? Should we export them?

What's next
Do you know if there are any follow-ups? (It can also be another RFC)

[davicostalf]

Theming is an important theme (ha) when discussing a design system that serves an admin used by different companies with their own brands.

I would focus on the fact that is not future-proof and it's not flexible enough for developers. Theming at least for me continues to be a nice-to-have, since - even in the long-term - I don't foresee this being necessary.

Future breaking changes potentially affecting more stakeholders

Separating concerns would only prevent breaking changes, no? In what way would breaking changes have a bigger impact?

Are users alowed to use raw token values? Should we export them?

What do you mean by raw token values?

[anitavincent]

Token breaking changes would affect us (we'd have to change our css-in-js packages) but also anyone who was using the csss variables directly, or anyone who built their own framework around them

raw token value would be "pink10" vs semantical "action-primary..."

[davicostalf]

Token breaking changes would affect us (we'd have to change our css-in-js packages) but also anyone who was using the csss variables directly, or anyone who built their own framework around them

I see. Maybe we should have documentation explaining the cons so anyone that chooses to do this can properly weight their choice.

raw token value would be "pink10" vs semantical "action-primary..."

Yes, I think we should export. It's better for teams to use these tokens if there are not sure what is the semantic, since it gives us visibility of new use cases. What do you think of calling these "absolute" tokens?

[matheusps]

How do you think we should handle the CSS variables? With Sass + Postcss? Or with some other tools like a style-dictionary: https://amzn.github.io/style-dictionary/#/README ?

[matheusps]

We implemented this on the styling framework.