Color token naming convention

[aagonzales]

Goal

As part of our next major release we want to update the names of the color tokens to users better understand how to apply color without needing to frequently reference a guide. We want the names to clearly articulate the purpose of the color and where/how to apply it.

Note: These token names and lists are based on the assumption that we will be implementing the inline theming proposal.

Existing convention

Currently, our existing token names are too abstract and only use numbers to distinguish between roles. For example, with text-01 the user knows its a text color but what kind of text?

There is also no real convention to the names and names have become inconsistent.

Two proposed naming conventions

Conventions

• A. [style modifier*]-[element]-[role]-[state]: See comment
• B. [property]-[role]-[style modifier]-[state]: See comment

Terms:

• Element: the part of the ui the token is being applied to, (ie border, button).
• Property: as in a css property
• Role: the different specific visual or functional purpose of a single element.
  • Roles can enforce hierarchy (ie primary, secondary) or refine the usage of the element (ie subtle, danger).
• Style modifier: * the style modifier is not a required in every token. It is only present in a few token categories. It is used to help group tokens that are used as a set (inverse) or interchangeably (support).
• State: the interactive state (ie hover, active) being applied to its token parent.

Overall we are (mostly) removing the terminating number labeling -01 -02 etc

Request for feedback:

• Which token naming convention do you prefer, A or B? Comment in the threads or 👍.
• What should we do about disabled token names? Color token naming convention #7827 (comment)
• Should we combine the old field-01 and ui-01 for this version or keep them separate? Color token naming convention #7827 (comment)
• Should we add a color- prefix? Color token naming convention #7827 (comment)
• What should the new ui-01 name be? Color token naming convention #7827 (comment)
• Do any of the names not make sense to you or would you not understand how to apply it? If so please leave a comment about which one and any name change suggestions.

Conclusion

#7827 (comment)

[aagonzales]

A. [style modifier*]-[element]-[role]-[state]

View full token list

• This convention keeps the naming structure similar to existing v10 names for there will be a familiarity in migration.
• It has shorter and more direct names.
• Style modifier creates a category among tokens that are used together or interchangeably. An example of a style modifier is "inverse" or "support"
• Tokens can have one word element names when calling out the primary or only use of color applied to an element. (ie background, highlight, layer, field)

Examples:

• [element]
  • $background
  • $layer
• [element]-[role]
  • $border-subtle
  • $text-helper
• [style modifier]-[element]
  • $inverse-background
  • $interactive-background
• [style modifier]-[element]-[role]
  • $inverse-support-success
• [element]-[state]
  • $background-hover
  • $layer-active
• [element]-[role]-[state]
  • $button-primary-active
  • $border-subtle-selected

[tessarodes]

I guarantee I'm missing a major implication but centering around an "element" feels natural to me.

[tw15egan]

I like having the modifier come first, easy to group and recognize similar tokens i.e inverse

[aagonzales]

B. [property]-[role]-[style modifier]-[state]

View full token list

• This naming convention is focused more on the (css?) property the value is applied too. It introduces new terms like "background" and "fill"
• However, some tokens will still begin with the "element" name versus a "property" to better aid in usage understanding.
• This results in longer compound names but clearer usage.
• Terms like "support" as removed in favor of using a property-role combination instead. For example support-01 is now fill-error
• The property or element always comes first
  • The exception is component level tokens in which case the component name would come first, ie toggle-off

Examples:

• [property]-[role]
  • $background-theme
  • $border-subtle
  • $text-helper
  • $fill-warning
• [property]-[style modifier]
  • $background-inverse
• [property]-[role]-[style modifier]
  • $fill-success-inverse
  • $button-primary-danger
• [property]-[role]-[state]
  • $background-theme-hover
  • $background-component-active

[aagonzales]

Fill can be applied to more than just svg. If it was an svg only color then it would be an icon- token. A lot of these "fill" colors have a clear role but I wasn't sure what property or element to assign them. Like I took away "support" in favor of "fill" but we can bring back some of those terms if we think it works better.

[laurenmrice]

I am a little torn between the two options but I think I am liking B more. I like the simplicity of A. B has a more complex naming convention but it explains the usage of each token better, which is what we were originally trying to achieve.

[laurenmrice]

The fill- naming conventions of the B set are ambiguous to me (similar reasons as to what Josh said above^). I feel like we could add support- back in for the support related tokens. For fill-interactive (interactive-04) it could just be interactive or something else?

[aagonzales]

support- is just not a property so breaks with the convention. But maybe it's better to have the familiar more easily understood term versus forcing a convention that is a worse experience.

[yumeforever]

I don't have a particular preference here, but having the element/root coming first seems more natural to me.
I like to be closer to the code implementation style too.

[aagonzales]

Question: disabled tokens

Should we break apart the abstract disabled tokens into more specific names? This would result in more disabled tokens going from 3 to about ~8. Or should we just keep it simple with abstract tokens.

[laurenmrice]

I would be fine with having different specific disabled tokens if it makes it easier for people to use them.

*The optional naming of text-white and icon-white for -on-color that you have in the notion tables seem odd if we end up introducing disabled tokens for them (it is the only token right now that would be specifying an actual color in the token name). Probably best to keep those as on-color like you are showing in this image here.

[tessarodes]

Interesting! Sure. I don't think it's confusing to break it out and could add clarity.

[aagonzales]

I was actually on the side of keeping the abstract because its less work lol but breaking them apart is probably the better systematic way to do it.

[yumeforever]

+1 it just make sense if you follow any of the other rationale, helps making things more descriptive

[aagonzales]

Question: field token

Should we combine the traditional field token with the main "layer"/"background-component" token? In our color modal the fields (old field-01) are the same color as the primary layer color (old ui-01).

Combining would result in less tokens but we would lose the ability to change field color separate from other ui containers. This is mostly a future concern or a "white label theme" concern.

Note: we no longer need two field tokens with inline theming.

[joshblack]

It might be nice to keep the field tokens for the use-cases you described, the alternative if we needed to distinguish the colors seems like it would be component tokens per form input component and that seems like a drag compared to just specifying field tokens. Let me know if there is an easier way though, I could easily be misunderstanding 👀

[laurenmrice]

I think we could just keep the field (layer/background-component) token for now and see how it plays out for awhile. If we eventually feel it is still redundant we could get rid of it. That is a good point about keeping it for future possibilities of “white labeling”.

[aagonzales]

If we keep both (which I do like), I think we'll just need to be more consistent about when you use field. I think in some places we use it in the field but not in other component areas, like here in dropdown.

Theoretically, should the list box background also be using field-01 then?

[yumeforever]

Keeping both and using the layer 01/02/03 makes sense to me

[aagonzales]

Question: color prefix

Should we prefix the tokens with color-? So tokens would read like $color-button-primary or $color-background.

If I remember correctly, @joshblack said we could make this essentially part of the file structure.

[joshblack]

@aagonzales yeah, we could definitely have this be related to the hierarchy/category/file versus having to be in the name.

[laurenmrice]

I don’t have a strong opinion about this but things I have noted:

• Adding a prefix will make the token names longer and add more repetition, which could make them harder to read or choose from.
• The token names without the prefix already resonate as a color token to me. I would be interested to know what other developers think about this.

[tw15egan]

Adding a prefix will make the token names longer and add more repetition, which could make them harder to read or choose from.

That's my concern as well. I wonder if we could alias them or something so that they work with / without a color prefix, if that is desired by some.

The token names without the prefix already resonate as a color token to me.

I agree. Especially since a dev would most likely be using in a context like so

body {
   background-color: $layer
}

[yumeforever]

I also dont see the need for the extra color-

[aagonzales]

Question: new ui-01 name

What should we call the new ui-01 token? In proposal A we call it layer and proposal B we call it background-component. Are there other names out there that may fit better? Material and Polaris call it a "surface".

[laurenmrice]

I like having the name layer for A. For B, another name we could try is background-layer?

[aagonzales]

Yeah I struggled with the name for B. My thinking was it always a "layer" when used for a component? I guess so? I think background-layer would work fine too. I was really torn with this one so hopefully other chime in with their thoughts.

[tw15egan]

I like layer as well. Another variation could be base-layer?

[aagonzales]

Oh base is an interesting term I hadn't thought about before.

[yumeforever]

With base-layer or background-layer, would it add the number too?
I.e.: base-layer-01 base-layer-02?
I prefer the Options B so I'd be ok with the shortest one, like base-layer.
Alternatively bg-layer could work, bg being abbreviation for background.

[aagonzales]

Alpha release final names

• View full list of tokens
• Conclusion: we decided on a bit of a hybrid of naming conventions based the feedback we were receiving (thanks everyone for that feedback btw). We are keeping the names as simple and straight forward as possible, not adding extra naming just for the sake of a convention.
• Convention: [element]-[role]-[style modifier]-[state]
  

[aagonzales]

Token names I'm still unsure about:

• layer-selected-inverse
• border-inverse
• layer-alt

[aagonzales]

layer-accent maybe? Yeah its not really an "alternate" to layer. It's more of a supporting color.

[tw15egan]

I like layer-accent

[laurenmrice]

I like layer-accent!

[tw15egan]

Do we want to get any more feedback on this one? Or should I go ahead and update the token in the theme package?

[aagonzales]

Let's go ahead and update it!