Should the spec include more semantic types?

[mkeftz]

It is useful to have more semantic information about a token and how it is to be used, especially when displaying previews of tokens or limiting which tokens are available to use.

However, some of the current token types are missing this semantic information. A good example of this is the dimension type. It is being used for fontSize, letterSpacing, borderRadius, width, padding, margin, etc.

Without knowing how a token is intended to be used, we are unable to display the correct token preview or limit where it is available. e.g. all dimension tokens would show up in a picker for a borderRadius property.

I can see a few options for adding this information to a token:

1. Add more semantic types — I can only think of a few which would cover most needs. These could be added as aliases. e.g. fontSize type as an alias for dimension.
2. Add an additional optional property on tokens specifically for this. e.g. semanticType or usedFor, but this feels overly complex
3. Add the semantic type in the token extensions. This is what we are doing at the moment, but removes some of the interoperability between different tools.

Is this something that has been considered? What is the suggested approach to handle this from a tooling perspective?

[c1rrus]

Thanks for raising this @mkeftz!

From what I recall, the main reason we've so far focussed on the types of the values rather than what they might be used for, is that the former felt like a much smaller and more manageable set of things to define. The concern was if instead of, say, a single color type we had things lie border-color, text-color, background-color, etc. it might be hard to know where to draw the line. "What about shadow-color?" someone might ask. "Why no highlight-color?" someone else might ask. And so on. We feared this might put us on a slippery slope to having a set of types that was some kind of superset of all the styling properties CSS, iOS, Android and others support.

But, as you've rightly, noted, it can be useful to provide some additional context that indicates where a token is meant to be used. For instance, design tools could use that to surface those tokens in the appropriate places.

We've mooted the idea of adding a new (optional) token property that could provide hints to tools about what a token should be used for. This is essentially the 2nd option you suggested - i.e. semanticType or usedFor. The permitted values of that property might be limited to just the most commonly used contexts (such as the ones commonly found in design tools like Figma).

Your first option of having new, semantic types which are aliases for the "plain" types is quite neat too. I think that could be quite elegant.

For the most part I think the difference between semantic type aliases and an additional property that provides to usage hints are stylistic. However, one potential benefit of a separate property is that we could allow it to also be an array of multiple usage hints.

E.g.:

{
  "color": {
    "foreground": {
      "type": "color",
      "value": "#000000",
      "used-for": "text-color" // single purpose
    }
  },
  "size": {
    "large": {
      "type": "dimension",
      "value": "3rem",
      "used-for": [ "margin", "padding", "font-size" ] // multiple purposes
     }
   }
}

And I agree that not sollving this in the spec and thus forcing folks to roll their own, bespoke solutions via extensions is sub-optimal.

[mkeftz]

Thank you @c1rrus, I assumed that was the reasoning around not including in the v1 of the spec. Also, I love the idea of having an array of values in a usedFor type property. This is similar to what we have in our internal token structure so works great.

I'm happy if you want to close this issue for now, as I don't think there is a clear solution from the spec point of view. I just wanted to check there wasn't a better option.

[c1rrus]

Great! I think we should keep this issue open so that others can comment as well though.

There's still some further details to figure out like what the set of permitted used-for values should be.

[natemoo-re]

I've been working on this exact problem for https://github.com/tokencss/tokencss and came up with a list of semantic types that dimension can fall under. All of the other types seems pretty clear cut for a single use.

Sharing my list here in case it's helpful, but these can certainly be implemented under extensions per the current draft. I'm using com.tokencss.scale for now.

• space
• size, (width and height as subsets of size)
• radius
• font-size
• font-weight
• line-height
• letter-spacing

[CITguy]

This might be relatable to #109.

[c1rrus]

Thanks for raising this issue @mkeftz. I've since noticed that Interplay has implemented something along the $usedFor proposal as an extension. Thanks also to @CITguy for sharing how you've done something similar as an extension for TokenCSS.

For what it's worth, I tried to compare how various tools let you use/specify the usages of design tokens aa while ago. I was exploring what a suitable set of $usedFor keywords might be. You can see my findings here: https://docs.google.com/spreadsheets/d/1NIxopYDkYTovkQHAoCl4wMj5ce5jp_hDjVLZqYqgaKo/edit

However, the format editors have discussed this and decided not to add a $usedFor property to the spec for now. While we think it - or something like it - could become a useful addition in the future, we want to keep the scope of initial of the initial spec version focussed on the essentials. We feel this is optional metadata for tokens, and therefore not required for tools to be able to store and exchange design token data with each other.

Once the format manages to gain widespread adoption, we can hopefully see whether there is more demand for this kind of functionality and, if so, what the most common usages are that we need to support.

To that end, I'd encourage you both to document your extensions (if you haven't already), so that others could add support for them to their tools. If extensions like yours gain broad support and usage, that would also provide a very clear "cowpath“ for future spec versions to pave.

In the meantime, we'll close this Github issue though since a decision has been reached not to add this to the spec for the time being.