Discuss component specific tokens

[sarahill]

As part of polaris token work, we are considering the need for component or pattern specific tokens.

We're finding there are cases across token groups where this makes sense.

To use color as an example, we have a few what we're currently calling "specialty roles" that get more specific in their application than the general role based tokens.

Below is a suggested pattern for component level tokens:

--p-color-{component}-{variant}-{default-token-structure}

examples:
--p-color-nav-surface
--p-color-avatar-fill
--p-color-avatar-one-icon-onfill

Points of discussion:

• Token structures that will work across multiple token groups? do they need to? It might vary
• Do semantic tokens always references alias tokens or can they directly reference primitive tokens?

[sarahill]

Original discussion in Slack:

[joe]
Was mapping this out today to in terms of the different token types we are gonna have. I do think we need this level of specificity.

1. Primitive
2. “Alias” (public primitive)
3. Semantic
4. Component

The ? I have is do we need to specify what the cascade is or can it be flexible. For example. Do component tokens reference all the way down to primitives, something else or can it be a mix? Do semantic tokens always references alias tokens or can they directly reference primitive tokens?

[sara]
My assumption is it might depend on the token group. I think (you might know more) that any token group referencing the size scale the component level tokens would reference the aliases. Although I think it's still nuanced. For example, for font-weight, you'd reference the "scale" (bold, semibold, etc.) and then make a component specific token from that (I think).
Color is one where I think you would have to reference the color scales. It feels limiting otherwise.

[joe]
Yeah my hunch is just doing what makes sense contextually is the best path forward.

[aaron]
Agreed, I think it needs to be flexible. I have a feeling that applying alias constraints to public primitives, semantics, and component specific tokens is going to be really nuanced and a point of contention.

[sam-b-rose]

I think this is a worth-while exploration. While not necessary for the system, I think it could add a centralized area of theme control that would reduce the need to update individual component files across the system.

This also seems easily reversible in my opinion. If component-level tokens aren't providing the value we hoped and only add complexity, we can migrate component tokens back to low-level alias or primitive tokens.

Doing a little code inspection research, looks like this is the strategy GitHub Primer uses as well: